%
% This is the LaTeX version of the RegexKitLite documentation.
%
% This is my (John Engelhart) first "big" LaTeX documentation project.
% As a result, it sucks, to put it mildly.  Well, in terms of how a big LaTeX document
% should be done.  I can't imagine that anyone would want to use this as an example of
% how to do documentation correctly.  There are lots of things that I would do differently,
% but that's how hindsight is.
%
% Originally, the HTML version of the documentation was "rough converted" to LaTeX using
% a couple of automated scripts.  This rough conversion was then manually massaged in to
% this result.  Unfortunately, this requires manually tracking changes to either the LaTeX
% or HTML version of the documentation and duplicating the changes in the other.
%
% Things you need to turn this documentation in to a PDF file:
%
% This documentation was largely written using the TeXShop.app program and typeset using XeLaTeX.
% Originally, the "TeX Live 2009" Macintosh distribution was used for the 2010-04-18 v4.0 release.
% Subsequently, the "TeX Live 2010" distribution became available.  As far as I know, the 2010
% distribution can be used to compile this document in to PDF without issues.  In fact, the 2010
% version of XeLaTeX manages to do a better job of compressing the resulting PDF, resulting in an
% approximate 50% reduction in the file PDF file size.
%
% Fonts used (The following are contemporary Adobe OTF versions of the fonts):
%  Warnock Pro
%  Myriad Pro
%  Letter Gothic Std
%
% Those are the primary fonts.  There may be a few additional fonts used for a handful of glyphs,
% but at this point I can't recall the specifics.
%
% In particular, the Letter Gothic font had a number of glyphs modified.  Of the top of my head these are:
%
% , ; = 0 " { }
%
% This TeX document could use a really good cleaning.  There's lots of cruft that's stuck around from
% various trials and experiments that was never removed.  Apologies for this.
%
% Like most TeX documents, you should probably run it through TeX more than once to get all the various
% references "correct".  If you have a mac TeX Live 2010 distribution and the appropriate fonts (or
% changed the base fonts used), you should be able to do something like:
%
% shell% xelatex RegexKitLite.tex
% 
% Two or three times.  You should then have a file "RegexKitLite.pdf".
%
% This documentation is covered by the BSD license.
%
% Copyright (c) 2008-2011, John Engelhart
% 
% All rights reserved.
% 
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are met:
% 
% * Redistributions of source code must retain the above copyright
% notice, this list of conditions and the following disclaimer.
% 
% * Redistributions in binary form must reproduce the above copyright
% notice, this list of conditions and the following disclaimer in the
% documentation and/or other materials provided with the distribution.
% 
% * Neither the name of the Zang Industries nor the names of its
% contributors may be used to endorse or promote products derived from
% this software without specific prior written permission.
% 
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
% "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
% LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
% A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
% OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
% SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
% TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
% PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
%
%

%\tracingcommands=1
%\tracingonline=1
%\tracingmacros=1
%\tracingoutput=1
%\tracingall

\documentclass[10pt,openany,notitlepage]{book}

\usepackage[MnSymbol]{mathspec}
\usepackage{xltxtra,xunicode}

\usepackage{changepage}

\usepackage{todonotes}
\newcommand{\RKLXXX}[1]{\todo[backgroundcolor=red,linecolor=red,size=\scriptsize]{#1}}
\newcommand{\RKLXXXIL}[1]{\todo[backgroundcolor=red,linecolor=red,size=\normalsize,inline]{#1}}

\usepackage{titlesec}

%\usepackage[pagestyles]{titlesec}
%\newpagestyle{tocpagestyle}{}
\usepackage{tocloft}
\tocloftpagestyle{fancy}

\usepackage{fancyhdr}
\pagestyle{fancy}
\usepackage{pstricks}
\usepackage{pst-blur}
\usepackage{pbox}
\usepackage{cellspace}
\usepackage{supertabular}
\usepackage{colortbl}
\usepackage{tabularx}
\usepackage{makecell}
\usepackage{booktabs}
\usepackage{listings}
\usepackage{ifthen}

\usepackage{enumitem}

\makeatletter
\def\enit@RKLNextLinestyle#1{%
  \hskip-\itemindent
  \global\everypar{%
    \@minipagefalse
    \global\@newlistfalse
    \if@inlabel
      \global\@inlabelfalse
      {\setbox\z@\lastbox
       \ifvoid\z@
         \kern-\itemindent
       \fi
       \sbox\z@{\hskip\labelindent#1\hskip\labelsep}%
         {\advance\leftskip-\leftmargin
          \advance\leftskip\labelindent
          \hskip-\labelsep
          #1%
          \par
          \nobreak
          \vskip-\parskip}%
       }%
       \setbox\@labels\box\voidb@x
    \fi
    \enit@break}}
\makeatother

\usepackage{pifont}
\usepackage{ragged2e}

\usepackage{datetime}
\renewcommand{\dateseparator}{-}
\yyyymmdddate
%\newdateformat{mydate}{\THEDAY-\THEMONTH-\THEYEAR}

\setlength{\cellspacetoplimit}{1.5pt}
\setlength{\cellspacebottomlimit}{1pt}

\usepackage{fancyvrb}


\usepackage{caption}
\DeclareCaptionLabelFormat{sclabel}{\textbf{\textsc{#1} {{\RKLPageNumberFont{}#2}}}}
\DeclareCaptionLabelSeparator{endash}{ \textendash{} }
\DeclareCaptionLabelSeparator{emdash}{ \textemdash{} }
\DeclareCaptionFormat{RKLFormat}{\RaggedRight{}\hspace{2ex}#1#2 #3}
\captionsetup{justification=raggedright,labelformat=sclabel,labelsep=endash,format=RKLFormat}

\usepackage{listing}

\usepackage{varioref}


\makeatletter

\DeclareRobustCommand\vpagerefx{\@ifstar{\let\vref@space\relax\vp@gerefx}{\let\vref@space\space\vp@gerefx}}
\def\vp@gerefx{\@ifnextchar[\@vpagerefx{\@vpagerefx[\reftextcurrent]}}
\def\@vpagerefx[#1]{\@ifnextchar[{\@@vpagerefx{#1}}{\@@vpagerefx{#1}[\unskip\vref@space]}}
\def\@@vpagerefx#1[#2]#3{%
  \leavevmode\unskip%
  \global\advance\c@vrcnt\@ne%
  \vref@pagenum\@tempa{\the\c@vrcnt @vr}%
  \vref@pagenum\@tempb{\the\c@vrcnt @xvr}%
  \vref@label{\the\c@vrcnt @xvr}%
  \ifx\@tempa\@tempb\else%
    \vref@err{\noexpand\vref or \noexpand\vpageref at page boundary \@tempb-\@tempa\space (may loop)}%
  \fi%
  \vrefpagenum\thevpagerefnum{#3}%
  \vref@space%
  \ifx\@tempa\thevpagerefnum%
    \def\@tempc{#1}%
    \ifx\@tempc\@empty \unskip \else{#1}\fi
  \else%
    #2%
  \fi%
  \vref@label{\the\c@vrcnt @vr}%
}

\makeatother


\usepackage{listings}



\usepackage[draft=false]{hyperref}

\hypersetup{
  pdfcreator={XeLaTeX with hyperref package},
  pdfinfo={
    Title={RegexKitLite},
    Subject={RegexKitLite Documentation},
    Author={John Engelhart}
  }
}
\hypersetup{pdfborder=0 0 0}
\hypersetup{colorlinks=true}

\newcommand{\RKLLinkColorRGBValues}{0.0, 0.31373, 0.78431}
\definecolor{RKLLinkColor}{rgb}{\RKLLinkColorRGBValues{}}
%\definecolor{PDFLinkColor}{rgb}{\RKLLinkColorRGBValues{}}

\hypersetup{linkcolor=RKLLinkColor}
\hypersetup{urlcolor=RKLLinkColor}

%\makeatletter
%\pdfstringdefDisableCommands{%
%\let~\textasciitilde
%\def\url{\pdfstringdefWarn\url}%
%\let\textcolor\@gobble
%\let\linebreak\@gobble
%}
%\makeatother


\lstdefinelanguage[Objective]{C2}[Objective]{C}
  {morekeywords={@dynamic,@package,@property,@synthesize,%
      readwrite,readonly,assign,retain,copy,nonatomic,%
      __attribute__}%
  }%

\lstdefinelanguage[Objective]{C}[99]{C}
  {morekeywords={@catch,@class,@encode,@end,@finally,@implementation,%
      @interface,@private,@protected,@protocol,@public,@selector,%
      @synchronized,@throw,@try,BOOL,Class,IMP,NO,Nil,SEL,YES,_cmd,%
      bycopy,byref,id,in,inout,nil,oneway,out,self,super},%
   moredirectives={import}%
  }%

\lstdefinelanguage[99]{C}%
  {morekeywords={_Bool,_Complex,_Imaginary,auto,break,case,char,%
      const,continue,default,do,double,else,enum,extern,float,for,%
      goto,if,inline,int,long,register,restrict,return,short,signed,%
      sizeof,static,struct,switch,typedef,union,unsigned,void,volatile,%
      while},%
   sensitive,%
   morecomment=[s]{/*}{*/},%
   morecomment=[l]//,
   morestring=[b]",%
   morestring=[b]',%
   moredelim=*[directive]\#,%
   moredirectives={define,elif,else,endif,error,if,ifdef,ifndef,line,%
      include,pragma,undef,warning}%
  }[keywords,comments,strings,directives]%

\lstset{
language=[Objective]{C2},
extendedchars=false,
basicstyle=\ttfamily,
keywordstyle=,
commentstyle=\itshape,
showstringspaces=false}


\newcommand{\RKLFontName}{Warnock Pro}
%\newcommand{\RKLFontName}{Arno Pro}
%\newcommand{\RKLFontName}{Minion Pro}
%\newcommand{\RKLFontName}{PalatinoLTStd-Roman}
\newfontface\RKLFont{\RKLFontName}
\newfontface\RKLPageNumberFont[Numbers={Monospaced,Lining}]{\RKLFontName}

% Minion is a bit to "small", but still good.
%\setmainfont{MinionPro-Regular}
%\setromanfont{PalatinoLTStd-Roman}
% Preferring warnock at the moment.
\setmainfont{\RKLFontName}

\setmathsfont(Digits,Latin,Greek)[Numbers={Lining,Proportional}]{\RKLFontName}
%\setmathrm{\RKLFontName}
%\setsansfont{\RKLFontName}
%\setmathrm{\RKLFontName}
%\setmathsf{\RKLFontName}


%\setmonofont[Scale=0.84,Numbers=SlashedZero]{LetterGothicStd}
%\setmonofont[Scale=0.8285]{LetterGothicStd}
\setsansfont[Scale=0.90]{Myriad Pro}
\setmonofont[Scale=0.80]{LetterGothicStd}
%\setsansfont[Scale=0.875]{Myriad Pro}

\setmonofont[Scale=0.84]{LetterGothicStd}
\setsansfont[Scale=0.92]{Myriad Pro}


%% MatchUppercase = 0.91528, MatchLowerCase = 0.83176

\newfontface\MnSymbolFont[Scale=MatchUppercase]{MnSymbol10}
\newfontface\PalatinoLinotypeFont[Scale=MatchUppercase]{Palatino Linotype}
\newfontface\Hiragino[Scale=MatchUppercase]{Hiragino Kaku Gothic ProN W3}
\newfontfamily\LucidaGrandeScaled[Scale=MatchUppercase]{Lucida Grande}
\newfontfamily\MyriadProScaled[Scale=MatchUppercase]{Myriad Pro}
\newfontfamily\LucidaSansTypewriterStdScaled[Scale=MatchLowercase]{Lucida Sans Typewriter Std}


\newfontface\STIXGeneralFont{STIXGeneral}
\newfontface\STIXGeneralScaledFont [Scale=MatchUppercase]{STIXGeneral}
\newfontface\DejaVuSansFont{DejaVu Sans}
\newfontface\DejaVuSansMonoFont{DejaVu Sans Mono}
\newfontface\DejaVuSansMonoScaledFont[Scale=MatchUppercase]{DejaVu Sans Mono}
\newfontface\AppleSymbolsFont{Apple Symbols}
\newfontface\AppleSymbolsScaledFont[Scale=MatchUppercase]{Apple Symbols}



%
% {Optima LT Std Demi}, {Thonburi Bold}, {ITC Avant Garde Gothic Std Medium}, {ITC Legacy Sans Std Medium}
%
%\newfontfamily\MenuFontScaled[Scale=0.90]{Myriad Pro}
\newfontfamily\MenuFontScaled[Scale=0.92]{Myriad Pro}


\setlength{\marginparwidth}{50pt}
\addtolength{\evensidemargin}{-1pt}
\setlength{\extrarowheight}{4pt}
\setlength{\textwidth}{442pt}
\setlength{\parindent}{0pt}
\setlength{\textheight}{600pt}
\setlength{\footskip}{41pt}
\setlength{\parskip}{5.75pt}
\setlength{\voffset}{-1in}
\setlength{\topmargin}{16.5pt}
\setlength{\headsep}{44.5pt}
\setlength{\headheight}{25pt}

\addtolength{\textheight}{31.5pt}


\renewcommand{\sectionmark}[1]{\markboth{#1}{}}

\fancyfootoffset[l]{50pt}

\DeclareUTFcharacter[\UTFencname]{x2009}{\textthinspace}
\DeclareUTFcharacter[\UTFencname]{x200A}{\texthairspace}
\DeclareUTFcharacter[\UTFencname]{x2264}{\textlesseq}
\DeclareUTFcharacter[\UTFencname]{x2265}{\textgreatereq}
\DeclareUTFcharacter[\UTFencname]{x23CE}{\textreturnsymbol}
\DeclareUTFcharacter[\UTFencname]{x21B5}{\textcrarr} % carriagereturn
%\DeclareUTFcharacter[\UTFencname]{x2245}{\textapproximatelyequalto}
%\newcommand{\textapproximatelyequalto}{{\PalatinoLinotypeFont{\char"2245}}}
\newcommand{\textapproximatelyequalto}{{\MnSymbolFont{\char"2245}}}
\DeclareUTFcharacter[\UTFencname]{x25B8}{\textsmallblackrightpointingpointer}
\DeclareUTFcharacter[\UTFencname]{x25BA}{\textblackrightpointingpointer}
\DeclareUTFcharacter[\UTFencname]{x21A9}{\textleftwardsarrowwithhook}%  <-
\DeclareUTFcharacter[\UTFencname]{x21AA}{\textrightwardsarrowwithhook}% ->
\DeclareUTFcharacter[\UTFencname]{x22EF}{\textmidlinehorizontalellipsis}% Like a normal ellipsis, but at mid level, not at the '.' level.

\newcommand{\hairspace}{\kern 0.333333em}
\newcommand{\ReturnSymbol}{{\Hiragino{}\textreturnsymbol{}}}
\newcommand{\ReturnKey}{{\LucidaGrandeScaled{}\textcrarr{}}}
\newcommand{\ShellCursor}{{\Hiragino{}{\char"258C}}}
%\newcommand{\XRightArrow}{{\LucidaGrandeScaled{}\textsmallblackrightpointingpointer{}}}
\newcommand{\MenuRightArrow}{{\LucidaGrandeScaled{}\textsmallblackrightpointingpointer{}}}

%\newcommand{\DeprecatedColor}{\addfontfeature{Color=FF0000}}
\newcommand{\DeprecatedColor}{\color{red}}


\newcommand{\Bd}[1]{\textbf{#1}}
\newcommand{\It}[1]{\textit{#1}}
\newcommand{\BdIt}[1]{\textit{\textbf{#1}}}
\newcommand{\BdItUl}[1]{\textit{\textbf{\underline{#1}}}}

\newcommand{\RKLLeftHookToRightHookDiscretionaryBreak}{\discretionary{\textleftwardsarrowwithhook}{\textrightwardsarrowwithhook}{}}
\newcommand{\RKLLeftHookDiscretionaryBreak}{\discretionary{\textleftwardsarrowwithhook}{}{}}
\newcommand{\RegexBreak}{\textleftwardsarrowwithhook{}\newline}
\newcommand{\DBRK}{\penalty-10000}
%\newcommand{\DBrk}{\discretionary{\,}{}{}}
\newcommand{\DBrk}{\penalty-1000}
%\newcommand{\DBrk}{\discretionary{\mbox{\hspace{0.001pt}}}{}{}}
\newcommand{\DLBRK}{\penalty-10000}
\newcommand{\DLBRk}{\penalty-9999}
\newcommand{\DLBrk}{\penalty0}
\newcommand{\DLNBrk}{\penalty1000}
\newcommand{\DLNBRk}{\penalty9999}
\newcommand{\DLNBRK}{\penalty10000}
%\newcommand{\XLBrk}{\penalty-250\linebreak}

\newcommand{\MenuText}[1]{{\protect\MenuFontScaled{}#1}}

\newcommand{\HardNobr}[1]{\mbox{#1}}
%\newcommand{\RegexKitLite}{\protect\HardNobr{RegexKit\protect\textit{Lite}}}
\newcommand{\RegexKitLite}[2][] {\HardNobr{RegexKit\protect\textit{Lite}\ifthenelse{\equal{#2}{}}{}{#2}}}



%\newcommand{\RKLDate}{\HardNobr{\today}}
\newcommand{\RKLDate}{\HardNobr{2010-04-18}}
\newcommand{\RKLVersion}{4.0}

\newcommand{\ObjectiveC}[1]{\HardNobr{Objective-C}}
\newcommand{\UTF}[1]{\HardNobr{\texttt{UTF-#1}}}

\newcommand{\SectionLink}[1]{\textit{#1}}

\newcommand{\Argument}[1]{\texttt{\textit{#1}}}

\newcommand{\Deprecated}[1]{{\protect\DeprecatedColor{}{#1}}}

%\newcommand{\CPPFlag}[1]{{\LucidaSansTypewriterStdScaled{}#1}}
\newcommand{\CPPFlag}[1]{{\Code{\Bd{#1}}}}

\newcommand{\UnicodeCharName}[1]{\texttt{#1}}
\newcommand{\UnicodeProperty}[1]{\texttt{#1}}
\newcommand{\QuotedText}[1]{\texttt{#1}}
\newcommand{\ConsoleText}[1]{\texttt{#1}}
\newcommand{\File}[1]{\texttt{#1}}
\newcommand{\Code}[1]{\texttt{#1}}
\newcommand{\CodeBolder}[1]{{\LucidaSansTypewriterStdScaled{}#1}}
\newcommand{\Regex}[1]{\texttt{#1}}
\newcommand{\RegexDef}[1]{\texttt{\It{#1}}}

\newcommand{\MacOSX}[2][]{\HardNobr{Mac OS X\ifthenelse{\equal{#2}{}}{}{#2}}}
\newcommand{\iPhoneOS}[2][]{\HardNobr{iPhone OS\ifthenelse{\equal{#2}{}}{}{#2}}}


%\newcommand{\SIGNATURE}[1]{\RaggedRight{}\Code{#1}\par}
\newcommand{\SIGNATURE}[1]{{\RaggedRight{}\Code{#1}}\par}
\newcommand{\Selector}[1]{\Bd{#1}}


\newcommand{\LabeledMethodSelector}[2]{\protect\subsection{{\protect#2}}\protect\label{#1}}

\newenvironment{RKLMethodsCodeFooter}{%
\titleformat{\subsection}{\normalfont\bfseries\Large\rmfamily}{\thesection.}{0pt}{}[\vskip-\parskip]%
\titlespacing{\subsection}{0pt}{0.5in plus 7.5pt minus 1pt}{3.5pt plus 0.5pt minus 0pt}%
\fancyfoot[C]{%
\begin{minipage}[t]{389pt}{\flushleft%
\raisebox{-0.75pt}{\Code{\rightmark}}\\
\raisebox{0.75pt}{\footnotesize{\textbf{\addfontfeature{Numbers={Monospaced,Lining}}\RKLDate~\textendash{}~\RKLVersion{}}}\hspace{5.3pt}\rule{0.6pt}{6pt}\hspace{5.3pt}{\bfseries\copyright\hspace{1.5pt}2008-2010 John Engelhart, All Rights Reserved}}
}
\end{minipage}
}%
}{%
\titleformat{\subsection}{\normalfont\fontsize{16pt}{16pt}\rmfamily}{\thesection.}{.5em}{}[\vspace{1.5pt}\titlerule]%
\titlespacing{\subsection}{0pt}{*3}{*1.25}%
\RKLSetupFancyHeadFoot{}%
}

\newenvironment{RKLMethods}{%
\titleformat{\subsection}{\normalfont\bfseries\Large\rmfamily}{\thesection.}{0pt}{} [\vskip-\parskip]%
\titlespacing{\subsection}{0pt}{0.5in plus 7.5pt minus 1pt}{3.5pt plus 0.5pt minus 0pt}%
}{%
\titleformat{\subsection}{\normalfont\fontsize{16pt}{16pt}\rmfamily}{\thesection.}{.5em}{}[\vspace{1.5pt}\titlerule]%
\titlespacing{\subsection}{0pt}{*3}{*1.25}%
}


\newcommand{\RKLTypeDefSection}[2]{\protect\subsection{{\protect#2}}\protect\label{#1}}

\newenvironment{RKLDiscussionEnv}{%
  \par\textbf{Discussion}\newline%
}{\par}

\newenvironment{RKLReturnValueEnv}{%
  \par\textbf{Return Value}\newline%
}{\par}

\newenvironment{RKLAvailabilityEnv}{%
  \par\textbf{Availability}\newline%
}{\par}

\newenvironment{RKLDeclaredInEnv}{%
  \par\textbf{Declared In}\newline%
}{\par}

\newenvironment{RKLParameters}{%
\par\textbf{Parameters}%
\begin{description}[topsep=-5.75pt, partopsep=0pt, parsep=2.5pt, itemsep=0pt, font=\normalfont\ttfamily\itshape, leftmargin=30pt, style=RKLNextLine] %
}{%
\end{description}
\vskip 5.75pt
\par
}

\newenvironment{RKLConstants}{%
\par\textbf{Constants}%
\begin{description}[topsep=-5.75pt, partopsep=0pt, parsep=2.5pt, itemsep=0pt, font=\normalfont\ttfamily, leftmargin=2.5ex, style=RKLNextLine] %
}{%
\end{description}
\vskip 5.75pt
\par
}


\newenvironment{RKLTasks}{%
\section{Tasks}
\titleformat{\subsection}{\normalfont\bfseries\fontsize{12pt}{12pt}\rmfamily}{\thesection.}{.5em}{}[]
\titlespacing{\subsection}{0pt}{*3}{*1.25}
}{%
\titleformat{\subsection}{\normalfont\fontsize{16pt}{16pt}\rmfamily}{\thesection.}{.5em}{}[\vspace{1.5pt}\titlerule]
\titlespacing{\subsection}{0pt}{*3}{*1.25}
}


\newenvironment{RKLTaskSection}[1]{%
\subsection{#1}
\begin{description}[topsep=-5.75pt, partopsep=0pt, parsep=4.125pt, itemsep=0pt, leftmargin=5ex, font=\normalfont, style=nextline] %
}{%
\end{description}
\vskip 5.75pt
\par
}

\newcommand{\RKLConstant}[3]{\item[#1] \label{#2}#3}


\newcommand{\RKLDiscussion}[1]{\begin{RKLDiscussionEnv}#1\end{RKLDiscussionEnv}}
\newcommand{\RKLReturnValue}[1]{\begin{RKLReturnValueEnv}#1\end{RKLReturnValueEnv}}
\newcommand{\RKLAvailability}[1]{\begin{RKLAvailabilityEnv}#1\end{RKLAvailabilityEnv}}
\newcommand{\RKLDeclaredIn}[1]{\begin{RKLDeclaredInEnv}\File{#1}\end{RKLDeclaredInEnv}}


\renewcommand\reftextcurrent      {~(p.\,\thevpagerefnum)}
\renewcommand\reftextfaceafter    {~(p.\,\thevpagerefnum)}
\renewcommand\reftextfacebefore   {~(p.\,\thevpagerefnum)}
\renewcommand\reftextafter        {~(p.\,\thevpagerefnum)}
\renewcommand\reftextbefore       {~(p.\,\thevpagerefnum)}
\renewcommand{\reftextfaraway}[1] {~(p.\,\pageref*{#1})}



\newcommand{\RKLTest}[1]{
\string#1
}


\newcommand{\RKLHref}[2]{\href{#1}{#2}}
\newcommand{\RKLSectionHref}[2]{\href{#1}{\SectionLink{#2}}}
\newcommand{\RKLCodeHref}[2]{\href{#1}{\Code{#2}}}

\newcommand{\RKLRef}[2]{\hyperref[#1]{#2}}
\newcommand{\RKLSectionRef}[2]{\RKLRef{#1}{\SectionLink{#2}}}
\newcommand{\RKLCodeRef}[2]{\RKLRef{#1}{\Code{#2}}}

\newcommand{\RKLPageRef}[2]{\hyperref[#1]{#2}\vpageref*{#1}}
\newcommand{\RKLSectionPageRef}[2]{\RKLPageRef{#1}{\SectionLink{#2}}}
\newcommand{\RKLCodePageRef}[2]{\RKLPageRef{#1}{\Code{#2}}}

\newcommand{\labeledchapter}[2]{\protect\chapter{\protect#2}\protect\label{\protect#1}}
\newcommand{\labeledsection}[2]{\section{#2}\label{#1}}
\newcommand{\labeledsubsection}[2]{\protect\subsection{#2}\protect\label{#1}}
\newcommand{\labeledsubsubsection}[2]{\subsubsection{#2}\label{#1}}


%\newcommand{\qattribute}[1]{{\par\vskip-22pt {\raggedleft\textemdash{} \textsc{#1}\hspace{2.5ex}\hbox{}\par}}}
\makeatletter
\newcommand*{\qattribute}[2][2.5ex]{{%
   \unskip\nobreak\hfil\penalty50%
   \hskip#1\hbox{}\nobreak\hfil\raisebox{-0.1875ex}{\textemdash{}~\textsc{#2}\hspace{#1}}%
   \parfillskip\z@\finalhyphendemerits=0\vskip0.1875ex\par}}
\makeatother


\newenvironment{RKLEnumerate}[3]{%
  \protect\begin{enumerate}[topsep=0pt, partopsep=0pt, itemsep=#2, parsep=0pt, label=#3, leftmargin=#1]%
}{\protect\end{enumerate}}

\newenvironment{RKLBulletList}{%
%  \protect\begin{enumerate}[leftmargin=12pt, topsep=0pt, partopsep=0pt, itemsep=5.75pt, parsep=0pt, label={\MnSymbolFont{}{\char"220E}}]%
  \protect\begin{enumerate}[leftmargin=12pt, topsep=0pt, partopsep=0pt, itemsep=5.75pt, parsep=0pt, label={\AppleSymbolsScaledFont{}{\char"25FC}}]%
}{\protect\end{enumerate}\par\vskip 0.75\parskip plus 0.075\parskip minus 0.0375\parskip}
%}{\protect\end{enumerate}}

\newenvironment{RKLBulletListTwo}{%
  \begin{enumerate}[leftmargin=12pt, topsep=5.75pt, partopsep=0pt, itemsep=5.75pt, parsep=0pt, label= {\AppleSymbolsScaledFont{}{\char"25FB}}]
}{\protect\end{enumerate}}

\newenvironment{RKLSeeAlso}{%
  \par\textbf{See Also}%
  \protect\begin{enumerate}[topsep=-5.75pt, partopsep=0pt, itemsep=0pt, parsep=0pt, label={}, leftmargin=2ex]%
}{%
\end{enumerate}
\vskip 5.75pt
\par
}


\definecolor{BoxQuoteFill}{rgb}{0.941176, 0.941176, 0.941176}
\definecolor{BoxQuoteLine}{rgb}{0.780392, 0.811764, 0.835294}
\definecolor{BoxQuoteShadow}{gray}{0.33}



\definecolor{BoxNoteFill}{rgb}{0.968627, 0.968627, 0.968627}
\definecolor{BoxNoteLine}{rgb}{0.631373, 0.647059, 0.662745}
\definecolor{BoxNoteShadow}{gray}{0.4}

\definecolor{BoxImportantFill}{rgb}{0.909804, 0.909804, 0.909804}
\definecolor{BoxImportantLine}{rgb}{0.066667, 0.066667, 0.066667}

\definecolor{BoxWarningFill}{rgb}{1.0, 1.0, 1.0}
\definecolor{BoxWarningLine}{rgb}{0.0, 0.0, 0.0}

\definecolor{BoxCautionFill}{rgb}{0.988235, 0.988235, 0.988235}
\definecolor{BoxCautionLine}{rgb}{0.0,      0.0,      0.0}



\definecolor{BoxHLBlueInner}{rgb}{0.494117647, 0.694117647, 0.874509803}
\definecolor{BoxHLBlueMiddle}{rgb}{0.662745098, 0.796078431, 0.917647058}
\definecolor{BoxHLBlueOuter}{rgb}{0.831372549, 0.898039215, 0.956862745}

\definecolor{BoxHLRedInner}{rgb}{1.0, 0.635, 0.635}
\definecolor{BoxHLRedMiddle}{rgb}{1.0, 0.715, 0.715}
\definecolor{BoxHLRedOuter}{rgb}{1.0, 0.796, 0.796}

\newenvironment{RKLRoundRectEnv}[1]{%
\hspace{3pt}\psframebox[cornersize=absolute, linearc=0.625ex, framesep=1.5pt, boxsep=false, linewidth=0.5pt, linecolor=lightgray]{#1}\hspace{3pt}%
}{%
%
}

%\newcommand{\RKLXXX}[1]{%
%\expandafter\psframebox[boxsep=false,linecolor=red,linewidth=0.4pt,linearc=0.625ex,cornersize=absolute]{
%\protect\begin{RKLRoundRectEnv}{{#1}}\protect\end{RKLRoundRectEnv}
%}
%}

\newcommand{\RKLRoundRect}[1]{\protect\begin{RKLRoundRectEnv}{{#1}}\protect\end{RKLRoundRectEnv}}

\newcommand{\RKLHighlightRect}[1]{%
\setbox0=\hbox{~}%
\dimen0 = \the\wd0%
\dimen1 = 0.5\dimen0%
\dimen2 = \dimen1 \advance \dimen2 by 0.5\dimen1%
\dimen3 = 0.5\dimen2%
\hspace{\the\dimen1}%
\dimen0 = \dimen3 \advance \dimen0 by -0.375pt%
\psframebox[cornersize=absolute, linearc=0.625ex, framesep=\the\dimen0, boxsep=false, linewidth=0.75pt, linecolor=BoxHLRedOuter]{%
\dimen0 = \dimen3 \advance \dimen0 by -0.225pt%
\psframebox[cornersize=absolute, linearc=0.625ex, framesep=\the\dimen0, boxsep=false, linewidth=0.45pt, linecolor=BoxHLRedMiddle]{%
\dimen0 = \dimen3 \advance \dimen0 by -0.075pt%
\psframebox[cornersize=absolute, linearc=0.625ex, framesep=\the\dimen0, boxsep=false, linewidth=0.15pt, linecolor=BoxHLRedInner]{#1}%
}%
}%
\hspace{\the\dimen1}%
}

%\newcommand{\RKLHighlightTightRect}[1]{%
%\psframebox[cornersize=absolute, linearc=0.625ex, framesep=0pt, boxsep=false, linewidth=0.75pt, linecolor=BoxHLRedOuter]{%
%\psframebox[cornersize=absolute, linearc=0.625ex, framesep=0.15pt, boxsep=false, linewidth=0.45pt, linecolor=BoxHLRedMiddle]{%
%\psframebox[cornersize=absolute, linearc=0.625ex, framesep=0.3pt, boxsep=false, linewidth=0.15pt, linecolor=BoxHLRedInner]{#1}%
%}%
%}%
%%\hspace{\the\dimen1}%
%}

\newenvironment{RKLBoxEnv}[3]{%
\par%
\vspace{0.5em}%
\setbox0=\hbox{#2\hspace{1.5ex}}%
\dimen0 = \linewidth \advance \dimen0 by - \the\wd0 \advance \dimen0 by - 2ex \advance \dimen0 by - 2em%
\dimen1 = \the\wd0 \advance \dimen1 by \dimen0 \advance \dimen1 by 0.5ex%
\hspace{1.0em}%
\psblurbox[#1]{\protect\begin{minipage}[c]{\dimen1}%
\protect\begin{minipage}[c]{\the\wd0}\raisebox{2pt}{#2\hspace{1.5ex}}\protect\end{minipage}%
\protect\begin{minipage}[c]{\dimen0}\vspace{1pt}{#3}\vspace{1pt}\protect\end{minipage}%
\protect\end{minipage}}%
\vspace{0.5em}%
\par%
}{%
%
}

\newcommand{\RKLBox}[2]{\protect\begin{RKLBoxEnv}{cornersize=absolute, linearc=0.75ex, shadowcolor=gray, shadowsize=2pt, blurradius=1pt}{\textbf{#1:}}{{#2}}\protect\end{RKLBoxEnv}}

\newcommand{\RKLBoxQuote}[1]{\protect\begin{RKLBoxEnv}{cornersize=absolute, linearc=0.75ex, shadowcolor=BoxQuoteShadow, shadowsize=2pt, blurradius=1pt, fillstyle=solid, fillcolor=BoxQuoteFill, linecolor=BoxQuoteLine}{}{{#1}}\protect\end{RKLBoxEnv}}


\newcommand{\RKLBoxNote}[1]{\protect\begin{RKLBoxEnv}{cornersize=absolute, linearc=0.75ex, shadowcolor=BoxNoteShadow, shadowsize=2pt, blurradius=1pt, fillstyle=solid, fillcolor=BoxNoteFill, linecolor=BoxNoteLine}{\textbf{Note:}}{{#1}}\protect\end{RKLBoxEnv}}
\newcommand{\RKLBoxImportant}[1]{\protect\begin{RKLBoxEnv}{cornersize=absolute, linearc=0.75ex, shadowcolor=gray, shadowsize=2pt, blurradius=1pt, fillstyle=solid, fillcolor=BoxImportantFill, linecolor=BoxImportantLine}{\textbf{Important:}}{{#1}}\protect\end{RKLBoxEnv}}
\newcommand{\RKLBoxWarning}[1]{\protect\begin{RKLBoxEnv}{cornersize=absolute, linearc=0.75ex, shadowcolor=gray, shadowsize=2pt, blurradius=1pt, linecolor=BoxWarningLine}{\textbf{Warning:}}{{#1}}\protect\end{RKLBoxEnv}}
\newcommand{\RKLBoxCaution}[1]{\protect\begin{RKLBoxEnv}{cornersize=absolute, linearc=0.75ex, shadowcolor=gray, shadowsize=2.5pt, blurradius=1.25pt, fillstyle=solid, fillcolor=BoxCautionFill, linecolor=BoxCautionLine}{\textbf{Caution:}}{{#1}}\protect\end{RKLBoxEnv}}




\newenvironment{RKLOffsetEnv}[1]{%
\dimen0 = \linewidth \advance \dimen0 by - #1%
\vspace{4pt}%
\hspace{#1}%
\protect\begin{minipage}[c]{\dimen0}
}{%
\protect\end{minipage}%
\vspace{4pt}%
}

\newcommand{\RKLOffset}[2]{%
\protect\begin{RKLOffsetEnv}{#1}%
\protect\begingroup%
#2%
\protect\endgroup%
\protect\end{RKLOffsetEnv}%
}




\newenvironment{RKLOffsetParEnv}[2]{%
\dimen0 = \linewidth \advance \dimen0 by - #1%
\vspace{4pt}%
\hspace{#1}%
\protect\parbox[c]{\dimen0}{#2}
}{%
\vspace{4pt}%
}


\newcommand{\RKLOffsetPar}[2]{\protect\begin{RKLOffsetParEnv}{#1}{#2}\protect\end{RKLOffsetParEnv}}

\makeatletter

\def\thickhrulefill{\leavevmode \leaders \hrule height 1pt\hfill \kern \z@}

\def\maketitle{%
  \null
  \thispagestyle{empty}
  \setlength{\hoffset}{-50pt}
  \addtolength{\textwidth}{50pt}
  \begin{flushleft}
    \vskip 34pt
    \rule{\textwidth}{0.5pt}
    \normalfont
    {\fontsize{29pt}{32pt}\rmfamily\raggedright  \@title\par}
    \vspace{6pt}
    {\raggedright {\fontsize{11pt}{11pt}\rmfamily Lightweight \ObjectiveC{} Regular Expressions for \MacOSX{}{} using the ICU Library}\par}
    \vspace{\stretch{1000}}
    {\raggedright \hspace{53.5pt}\raisebox{-86.69pt}{\textbf{\addfontfeature{Numbers={Monospaced,Lining}}\@date~\textendash{}~\RKLVersion{}}}}
  \end{flushleft}
  \vfill

  \pagebreak
  \null
  \thispagestyle{empty}
  \setlength{\hoffset}{-89pt}
  \addtolength{\textwidth}{89pt}

{\small
\begin{tabular}[t]{p{150pt}p{150pt}}{\begin{flushleft}\unskip
\RegexKitLite{}

© 2008-2010 John Engelhart

All rights reserved.\vspace{1em}

Apple, the Apple logo, Cocoa, Mac, Mac OS, Macintosh, Objective-C, and Safari are trademarks of Apple Inc., registered in the United States and other countries.\vspace{1em}

Although this document follows the style conventions of Apples documentation, it is not meant to imply any form of endorsement, sponsorship, or association with Apple.\vspace{1em}

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and the author was aware of a trademark claim, the designations have been printed with initial capital letters, in all capitals, or capitalized as appropriate for the trademark.\vspace{1em}

Every effort has been made to ensure that the information in this document is accurate, but no express or implied warranty of any kind is made and the author assumes no responsibility for any errors, inaccuracies, or omissions.  No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information or programs contained herein.\end{flushleft}}

{\fontspec[Scale=MatchLowercase]{Courier}THIS DOCUMENTATION IS PROVIDED "AS IS", IS FURNISHED FOR INFORMATIONAL USE ONLY, AND IS SUBJECT TO CHANGE WITHOUT NOTICE. THE AUTHOR DISCLAIMS ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY \linebreak OF\nolinebreak[4]\hspace{\stretch{0.5}} MERCHANTABILITY,\nolinebreak[4]\hspace{\stretch{0.5}} CLAIMS}

&

{\fontspec[Scale=MatchLowercase]{Courier}OF ACCURACY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT OF THIRD-PARTY RIGHTS. IN NO EVENT WILL THE AUTHOR BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.} \\
\end{tabular}
}\vfill\null\clearpage
}

\makeatother



\setcounter{secnumdepth}{0}

\renewcommand{\chaptermark}[1]{\markboth{#1}{#1}}
\renewcommand{\sectionmark}[1]{\markright{#1}}
\renewcommand{\subsectionmark}[1]{\markright{#1}}
\renewcommand{\headrulewidth}{0pt}


\renewcommand{\cftchapfont}{\bfseries\large}
\renewcommand{\cftchapleader}{\bfseries\cftdotfill{\cftchapdotsep}}
\renewcommand{\cftchappagefont}{\bfseries}
\renewcommand{\cftchappresnum}{\normalcolor\normalsize{\hspace{-15ex}{\setlength{\RKLTocLength}{\textwidth}\addtolength{\RKLTocLength}{15ex}%
%{\raisebox{-5.5pt}{\color{gray}\rule{\RKLTocLength}{0.5pt}}\hspace{-\RKLTocLength}%
{{\color{gray}\rule[-5.5pt]{\RKLTocLength}{0.7pt}}\hspace{-\RKLTocLength}%
%\textsc{Chapter }%
}}}}
\renewcommand{\cftchapafterpnum}{\vspace{5pt}}


\renewcommand{\cftchapdotsep}{\cftnodots}
\renewcommand{\cftsecdotsep}{\cftnodots}
\renewcommand{\cftsubsecdotsep}{\cftnodots}
\renewcommand{\cftsubsubsecdotsep}{\cftnodots}
\renewcommand{\cftfigdotsep}{\cftnodots}
\renewcommand{\cfttabdotsep}{\cftnodots}

\newcommand{\RKLTableOfContents}{
\fancyhead{}\fancyfoot{}%
\fancyfoot[L]{{\raisebox{-2pt}{\large\RKLPageNumberFont\bfseries\thepage}}}%
\fancyfoot[C]{%
\begin{minipage}[t]{389pt}{\flushleft%
\raisebox{-0.75pt}{}\\%
\raisebox{0.75pt}{\footnotesize{\textbf{\addfontfeature{Numbers={Monospaced,Lining}}\RKLDate~\textendash{}~\RKLVersion{}}}\hspace{5.3pt}\rule{0.6pt}{6pt}\hspace{5.3pt}{\bfseries\copyright\hspace{1.5pt}2008-2010 John Engelhart, All Rights Reserved}}%
}\end{minipage}}
\currentpdfbookmark{Contents}{pdfContents}
\tableofcontents
}

\newcommand{\RKLSetupFancyHeadFoot}{%
\fancyhead{}\fancyfoot{}%
%\fancyhead[L]{{\normalfont{\textsc{Chapter {\RKLPageNumberFont\thechapter}\newline\leftmark}}}}%
%\fancyhead[L]{{\normalfont{\textsc{{\chaptername{} \RKLPageNumberFont\thechapter}\newline\leftmark}}}}%
\fancyhead[L]{{\normalfont{{\chapternumberline{}}\newline\leftmark}}}%
\fancyfoot[L]{{\raisebox{-2pt}{\large\RKLPageNumberFont\bfseries\thepage}}}%
\fancyfoot[C]{%
%\begin{minipage}[t]{389pt}{\flushleft%
\hspace{10pt}%
\begin{minipage}[t]{399pt}{\flushleft%
\hbox{\raisebox{-0.75pt}{\hbox{\rightmark}}}%\\%
\raisebox{0.75pt}{\footnotesize{\textbf{\addfontfeature{Numbers={Monospaced,Lining}}\RKLDate~\textendash{}~\RKLVersion{}}}\hspace{5.3pt}\rule{0.6pt}{6pt}\hspace{5.3pt}{\bfseries\copyright\hspace{1.5pt}2008-2010 John Engelhart, All Rights Reserved}}%
}\end{minipage}}%
}

\newcommand{\chapternumberline}{}
\newcommand{\chapternameformat}[1]{\protect\textsc{#1}}
\newcommand{\chapternumberformat}[1]{{\protect\RKLPageNumberFont{#1}}}

\makeatletter
\renewcommand\chapter{\if@openright\cleardoublepage\else\clearpage\fi%
                    \thispagestyle{fancy}%
                    \global\@topnum\z@%
                    \@afterindentfalse%
                    \if@mainmatter\renewcommand{\chapternumberline}{{\chapternameformat{\chaptername}} {\chapternumberformat{\thechapter}}}\fi%
                    \secdef\@chapter\@schapter}

\def\@chapter[#1]#2{\ifnum \c@secnumdepth >\m@ne
                       \if@mainmatter
                         \refstepcounter{chapter}%
                         \typeout{\@chapapp\space\thechapter.}%
                         \addcontentsline{toc}{chapter}%
                                   {\protect\numberline{\chapternumberline}#1}%
                       \else
                         \addcontentsline{toc}{chapter}{#1}%
                       \fi
                    \else
                      \addcontentsline{toc}{chapter}{#1}%
                    \fi
                    \chaptermark{#1}%
                    \addtocontents{lof}{\protect\addvspace{10\p@}}%
                    \addtocontents{lot}{\protect\addvspace{10\p@}}%
                    \if@twocolumn
                      \@topnewpage[\@makechapterhead{#2}]%
                    \else
                      \@makechapterhead{#2}%
                      \@afterheading
                    \fi}

\makeatother

\newcommand{\RKLAppendix}{%
\vfill\null\clearpage%
\appendix%
\renewcommand{\chaptername}{Appendix}%
\renewcommand{\chapternumberformat}[1]{\protect\textsc{##1}}%
}

\titleformat{\chapter}[block]{\normalfont\Huge}{}{0pt}{}[%
\vspace{4pt}%
{%
\setlength{\unitlength}{1sp}%
\dimen0 = \linewidth \advance \dimen0 by 50pt
\linethickness{0.4pt}
\begin{picture}(\number\dimen0, 1)
\put(-3276800, 0){\line(\number\dimen0, 0){\number\dimen0}}
\end{picture}
}
]
\titlespacing{\chapter}{0pt}{-1.625ex}{-2ex}

\titleformat{\section}{\normalfont\fontsize{19pt}{19pt}\rmfamily}{\thesection.}{.5em}{}
\titlespacing{\section}{-50pt}{*3}{*3}
\titleformat{\subsection}{\normalfont\fontsize{16pt}{16pt}\rmfamily}{\thesection.}{.5em}{}[\vspace{1.5pt}\titlerule]
\titlespacing{\subsection}{0pt}{*3}{*1.25}
\titleformat{\subsubsection}{\normalfont\large}{\thesection.}{.5em}{}[\vspace{1.5pt}\titlerule]
\titlespacing{\subsubsection}{0pt}{*3}{*1.25}

\title{\RegexKitLite{}}
\author{John Engelhart}
\date{\RKLDate}

\newsavebox{\RKLTempSaveBox}
\newsavebox{\RKLTocChapSaveBox}
\newdimen{\RKLTocDimen}
\newlength{\RKLTocLength}


%\DeclareCaptionDefaultJustification{\raggedright}

\begin{document}
\frontmatter

\maketitle
\setlength{\oddsidemargin}{88pt}
\addtolength{\textwidth}{-50pt}
\addtolength{\textwidth}{-89pt}
\setlength{\hoffset}{-50pt}

\RKLTableOfContents{}

\mainmatter
\RKLSetupFancyHeadFoot{}

%\labeledchapter{IntroductiontoRegexKitLite}{Introduction to \RegexKitLite{}}
\chapter*{Introduction to \RegexKitLite{}}%
\chaptermark{Introduction to \RegexKitLite{}}%
\renewcommand{\chapternumberline}{\protect\textsc{Introduction}}%
\addcontentsline{toc}{chapter}{\protect\numberline{\chapternumberline}{Introduction to \protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite}}}%
\label{IntroductiontoRegexKitLite}

This document introduces \RegexKitLite{} for \MacOSX{}. \RegexKitLite{} enables easy access to regular expressions by providing a number of additions to the standard \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/ObjC\_classic/index.html}{Foundation} \Code{NSString} class. \RegexKitLite{} acts as a bridge between the \Code{NSString} class and the regular expression engine in the \RKLSectionHref{http://site.icu-project.org/}{International Components for Unicode}, or ICU, dynamic shared library that is shipped with \MacOSX{}.

\section{\protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} Highlights}

\begin{RKLBulletList}
  \item Uses the regular expression engine from the ICU library which is shipped with \MacOSX{}.
  \item Automatically caches compiled regular expressions.
  \item Uses direct access to a strings \UTF{16} buffer if it is available.
  \item Caches the \UTF{16} conversion that is required by the ICU library when direct access to a strings \UTF{16} buffer is unavailable.
  \item Small size makes it ideal for use in iPhone applications.
  \item Multithreading safe.
  \item \HardNobr{64-bit} support.
  \item Custom DTrace probe points.
  \item Support for \MacOSX{ 10.5} Garbage Collection.
  \item Support for the Blocks language extension.
  \item Uses \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation} for greater speed.
  \item Very easy to use, all functionality is provided by a category extension to the \Code{NSString} class.
  \item Consists of two files, a header and the \ObjectiveC{} source.
  \item Xcode 3 integrated \RKLPageRef{NSStringRegexKitLiteAdditionsXcode3IntegratedDocumentation}{documentation available}.
  \item Distributed under the terms of the \RKLSectionPageRef{LicenseInformation}{BSD License}.
\end{RKLBulletList}

\section{Who Should Read This Document}

This document is intended for readers who would like to be able to use regular expressions in their\DLBRK{} \ObjectiveC{} applications, whether those applications are for the \MacOSX{} desktop, or for the iPhone.

This document, and \RegexKitLite{}, is also intended for anyone who has the need to search and manipulate \Code{NSString} objects. If you've ever used the \Code{NSScanner}, \Code{NSCharacterSet}, and \Code{NSPredicate} classes, or any of the the \Code{NSString} \Code{rangeOf\textellipsis{}} methods, \RegexKitLite{} is for you.

Regular expressions are a powerful way to search, match and extract, and manipulate strings.  \RegexKitLite{} can perform many of the same operations that \Code{NSScanner}, \Code{NSCharacterSet}, and \Code{NSPredicate} perform, and usually do it with far fewer lines of code.  As an example, \RKLSectionPageRef{RegexKitLiteCookbook_ParsingCSVData}{\RegexKitLite{} Cookbook - Parsing CSV Data} contains an example that is just over a dozen lines, but is a full featured CSV, or Comma Separated Value, parser that takes a CSV input and turns it in to a \Code{NSArray} of \Code{NSArray}s.

\section{Organization of This Document}

This document follows the conventions and styles used by Apples documentation and is divided in to two main parts:

\begin{RKLBulletList}
  \item The \It{Class Reference} part, \RKLPageRef{RegexKitLiteNSStringAdditionsReference}{\RegexKitLite{} \Code{NSString} Additions Reference}.
  \item The \It{Programming Guide} part, which consists of the following chapters:
    \begin{RKLBulletListTwo}
      \item \RKLPageRef{RegexKitLiteOverview}{\RegexKitLite{} Overview}
      \item \RKLPageRef{UsingRegexKitLite}{Using \RegexKitLite{}}
      \item \RKLPageRef{ICUSyntax}{ICU Syntax}
      \item \RKLPageRef{RegexKitLiteCookbook}{\RegexKitLite{} Cookbook}
      \item \RKLPageRef{AddingRegexKitLitetoyourProject}{Adding \RegexKitLite{} to your Project}
    \end{RKLBulletListTwo}
\end{RKLBulletList}\vskip \parskip

Additional information can be found in the following sections:

\begin{RKLBulletList}
  \item \RKLPageRef{ReleaseInformation}{Release Information}, which contains the \RKLPageRef{ReleaseInformation_ThisVersion}{Release Notes for \RegexKitLite{ \RKLVersion{}}}
%  \item \RKLSectionPageRef{Epilogue}{Epilogue}%
  \item \RKLPageRef{LicenseInformation}{License Information}, which contains the \RegexKitLite{} \It{BSD License}.
\end{RKLBulletList}

%\section{Development Services}

%The author of \RegexKitLite{} is available on a consulting basis for your \MacOSX{}{} or iPhone projects, and at the time of this writing, also available for hire on a full-time basis.  Contact {\addfontfeature{Color=FF0000}JOHNE} to discuss opportunities.

\section{Supporting \protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} through Financial Donations}

A significant amount of time and effort has gone in to the development of \RegexKitLite{.} Even though it is distributed under the terms of the \RKLSectionRef{LicenseInformation}{BSD License}, you are encouraged to contribute financially if you are using \RegexKitLite{} in a profitable commercial application. Should you decide to contribute to \RegexKitLite{,} please keep the following in mind:

\begin{RKLBulletList}
  \item What it would have cost you in terms of hours, or consultant fees, to develop similar functionality.
  \item The \RKLHref{http://www.ohloh.net/p/RegexKitLite}{ohloh.net Project Cost} metric, \$91,529 as of 4.0, does not factor in the cost of writing documentation, which is where most of the effort is spent.
  \item The target audience for \RegexKitLite{} is very small, so there are relatively few units "sold".
\end{RKLBulletList}

You can contribute by visiting SourceForge.net's \RKLHref{http://sourceforge.net/donate/index.php?group\_id=204582}{donation page for \RegexKitLite{}}.

\RKLBoxImportant{You are always required to acknowledge the use of \RegexKitLite{} in your product as specified in the terms of the \RKLSectionRef{LicenseInformation}{BSD License}.}

\section{Download}

You can download \RegexKitLite{} distribution that corresponds to this version of the documentation here\textendash{} \RKLHref{http://downloads.sourceforge.net/regexkit/RegexKitLite-4.0.tar.bz2}{\File{RegexKitLite-4.0.tar.bz2}}, 135.9K. To be automatically notified when a new version of \RegexKitLite{} is available, add the \RKLPageRef{NSStringRegexKitLiteAdditionsXcode3IntegratedDocumentation}{\RegexKitLite{} documentation feed} to Xcode.

\section{Reporting Bugs}

You can file bug reports, or review submitted bugs, at the following URL:

\hspace{2.5ex}\RKLHref{http://sourceforge.net/tracker/?group\_id=204582\&atid=990188}{\Code{http://sourceforge.net/tracker/?group\_id=204582\&atid=990188}}

\RKLBoxNote{Anonymous bug reports are no longer accepted due to spam.  A SourceForge.net account is required to file a bug report.}

\section{Contacting The Author}

The author can be contacted at \RKLHref{mailto:regexkitlite@gmail.com}{\ConsoleText{regexkitlite@gmail.com}}.

\section{Conventions}

The following typographic conventions are used in this document:

\begin{description}[topsep=0pt, partopsep=0pt, parsep=2.5pt, itemsep=0pt, font=\normalfont, leftmargin=30pt, style=RKLNextLine] %
  \item[\It{Italic}] Book titles, cross-references to other documents, new terms, and terms to be emphasized.
  \item[\color{RKLLinkColor}Colored Text] Indicates a hyperlink, either to another part of this document, or an external URL.
  \item[\Code{Fixed Width}] Program code, applications, commands, files and directories, and the output of shell programs.
  \item[\Code{Fixed\textvisiblespace{}Width\textvisiblespace{}A\textvisiblespace{}\textvisiblespace{}B\textvisiblespace{}C}] Used when it is necessary to unambiguously identify spaces.
  \item[\Code{\Bd{Fixed Width Bold}}] C preprocessor defines and user typed input in a shell.
  \item[\Code{\It{Fixed Width Italic}}] Placeholder for user-supplied values and function or method parameters.
  \item[\MenuText{File \MenuRightArrow{} Save As\textellipsis{}}] Menus and menu selections are in a sans serif font.
  \item[\Code{@"\textbackslash{}\textbackslash{}s*(\textbackslash{}\textbackslash{}w\RKLHighlightRect{\Code{+)?}}";}] A colored ring is used to draw attention to a specific part of the text, such as highlighting the difference between two examples.
  \item[\ReturnKey{}] Used to indicate when the return key is pressed in a shell.
\end{description}

This document includes text where the exact sequence of characters has specific meaning, such as program code and regular expressions.  When printed, text that was meant to span a single line only will have to be split across multiple lines in order to fit within the fixed width of a page.  The '\Code{\textleftwardsarrowwithhook{}}' glyph is used to visually indicate when a line has been split across multiple lines, and does not represent part of the intended sequence of characters.  For example:

\begin{tabularx}{0.7\textwidth}{|l|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Description} & \Bd{Regex} \\\hline
Floating Point with Exponent & \Regex{[+\textbackslash{}-]?(?:[0-9]*\textbackslash{}.[0-9]+|\RKLHighlightRect{\textleftwardsarrowwithhook{}}\newline{}[0-9]+\textbackslash{}.)(?:[eE][+\textbackslash{}-]?[0-9]+)?} \\\hline
\end{tabularx}

The same line shown without splitting it across multiple lines:

\begin{tabular}{|l|l|}\hline
\rowcolor[gray]{0.8862745} \Bd{Description} & \Bd{Regex} \\\hline
\makecell[lc]{\vtop{\hbox {Floating Point with Exponent}\hbox{\rule{0pt}{0.85ex}}}}&
\makecell[lc]{\vtop{\hbox{\Regex{[+\textbackslash{}-]?(?:[0-9]*\textbackslash{}.[0-9]+\RKLHighlightRect{|[}0-9]+\textbackslash{}.)(?:[eE][+\textbackslash{}-]?[0-9]+)?}}\hbox{\rule{0pt}{0.85ex}}}}\\\hline
\end{tabular}

For aesthetic purposes, it is sometimes useful to indent the continuation of the split line.  When this is done, the '\Code{\textrightwardsarrowwithhook{}}' glyph is used to indicate where the continuation begins:

\begin{lstlisting}[escapeinside=``,belowskip=0pt]
printf("%5d: a long, unbroken ABC`\RKLHighlightRect{\textleftwardsarrowwithhook{}}`
      `\RKLHighlightRect{\textrightwardsarrowwithhook{}}`def string.\n", x);
\end{lstlisting}

The same line shown without splitting it across multiple lines:

\begin{lstlisting}[escapeinside=``,belowskip=0pt]
printf("%5d: a long, unbroken `\RKLHighlightRect{ABCdef}` string.\n", x);
\end{lstlisting}

When the command that you need to type in to a shell is split across lines, a \Code{\Bd{\textbackslash{}}} (backslash) is added to the end of the line where the split was made.  These end of line backslashes are optional, you can either enter them as \Code{\Bd{\textbackslash{}}\ReturnKey{}}, in which case the shell will wait for additional input, or they can be removed entirely, with the command spanning a single line.  An example:

\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{gcc someFile.m \textellipsis{}\It{more gcc arguments}\textellipsis{} -framework Foundation \RKLHighlightRect{\textbackslash{}}}
       \Bd{-licucore -o someFile}\ReturnKey{}
shell% \ShellCursor{}
\end{Verbatim}

\section{Colophon}

The text font is Adobe Warnock Pro, the fixed width font is Letter Gothic, and the sans serif font is Adobe Myriad Pro.  MnSymbol10 and Apple Symbol are used for a small number of glyphs.

This document was typeset with \XeLaTeX{} and \TeX{}Shop.app on \MacOSX{} and makes use of a number of freely available \LaTeX{} packages\textendash{} \File{fancyhdr}, \File{fancyvrb}, \File{hyperref}, \File{listings}, \File{pstricks}, \File{pst-blur},  \File{tabularx}, \File{titlesec}, \File{tocloft}, and others, either directly or indirectly through inclusion by another package.  The author wishes to thank the authors of these packages, including the authors of \TeX{}, \LaTeX{}, \XeLaTeX{}, and \TeX{}Shop, for making them freely available.

\labeledchapter{RegexKitLiteOverview}{\protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} Overview}

While \RegexKitLite{} is not a descendant of the \File{RegexKit.framework} source code, it does provide a small subset of \RKLSectionHref{http://regexkit.sourceforge.net/}{RegexKits} \Code{NSString} methods for performing various regular expression tasks. These include determining the range that a regular expression matches within a string, easily creating a new string from the results of a match, splitting a string in to a \Code{NSArray} with a regular expression, and performing search and replace operations with regular expressions using common \Regex{\$}\Argument{n} substitution syntax.

\RegexKitLite{} uses the regular expression provided by the ICU library that ships with \MacOSX{}.  The two files, \File{RegexKitLite.h} and \File{RegexKitLite.m}, and linking against the \File{/usr/lib/libicucore.dylib} ICU shared library is all that is required.  Adding \RegexKitLite{} to your project only adds a few kilobytes of overhead to your applications size and typically only requires a few kilobytes of memory at run-time.  Since a regular expression must first be compiled by the ICU library before it can be used, \RegexKitLite{} keeps a small \HardNobr{4-way} set associative cache with a least recently used replacement policy of the compiled regular expressions.

%\RKLBoxWarning{Apple does not officially support linking to the \File{libicucore.dylib} library.  See \RKLHref{http://lists.apple.com/archives/xcode-users/2005/Jun/msg00633.html}{this \HardNobr{\ConsoleText{Xcode-users@lists.apple.com}} message} for more information.}
%
%If you are uncomfortable with linking against \File{/usr/lib/libicucore.dylib}, you can build your own version of of ICU. To link to your custom build of ICU, \RegexKitLite{} provides the compile time preprocessor define flag \CPPFlag{RKL\_APPEND\_TO\_ICU\_FUNCTIONS}.  A custom version of ICU will typically have the ICU version appended to all of its functions, and \CPPFlag{RKL\_APPEND\_TO\_ICU\_FUNCTIONS} allows you to append that version to the ICU functions that \RegexKitLite{} calls.  For example, passing \HardNobr{\ConsoleText{-DRKL\_APPEND\_TO\_ICU\_FUNCTIONS=\_4\_0}} to \ConsoleText{gcc} would cause the ICU function \Code{uregex\_find()} used by \RegexKitLite{} to be called as \Code{uregex\_find\_4\_0()}.
%
%Unfortunately, this is just one of the simpler steps of many that are required to include a custom build of ICU with your application.  Adding a custom build of ICU to your application is a \BdIt{non-trivial} process.  There is no simple set of steps that can be followed that are appropriate for every use.  ICU is a very large and complex library which is nearly \BdIt{ten megabytes} in size using the default options.  Apple provides the full source to the version of ICU that they supply with \MacOSX{}. At the time of this writing, the latest version available was for \MacOSX{ 10.6.2}\textendash{} \RKLHref{http://www.opensource.apple.com/tarballs/ICU/ICU-400.38.tar.gz}{\File{ICU-400.38.tar.gz}}.


%\RKLBoxWarning{As of \MacOSX{ 10.6}, Apple does not officially support linking to the \File{libicucore.dylib} library.  See \RKLHref{http://lists.apple.com/archives/xcode-users/2005/Jun/msg00633.html}{this \HardNobr{\ConsoleText{Xcode-users@lists.apple.com}} message} for more information.}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://regexkit.sourceforge.net/}{RegexKit Framework}
  \item \RKLSectionHref{http://site.icu-project.org/}{International Components for Unicode}
  \item \RKLSectionHref{http://www.unicode.org/}{Unicode Home Page}
\end{RKLSeeAlso}

%\section{Support for ICU Regular Expressions}
\section{Official Support from Apple for ICU Regular Expressions}

%\subsection{Regular Expression Support in Mac OS X}
\subsection{Mac OS X}

As of \MacOSX{ 10.6}, the author is not aware of any official support from Apple for linking to the\DLBRK{} \File{libicucore.dylib} library.  On the other hand, the author is unaware of any official prohibition against it, either.  Linking to the ICU library and making use of the ICU regular expression API is slightly different than making use of private, undocumented API's.  There are a number of very good reasons why you shouldn't use private, undocumented API's, such as:

\begin{RKLBulletList}
  \item The undocumented, private API is not yet mature enough for Apple to commit to supporting it.  Once an API is made "public", developers expect future versions to at least be compatible with previously published versions.
  \item The undocumented, private API may expose implementation specific details that can change between versions.  Public API's are the proper "abstraction layer boundary" that allows the provider of the API to hide implementation specific details.
\end{RKLBulletList}

The ICU library, on the other hand, contains a "published, public API" in which the ICU developers have committed to supporting in later releases, and \RegexKitLite{} uses only these public APIs.  One could argue that Apple is not obligated to continue to include the ICU library in later versions of \MacOSX{}, but this seems unlikely for a number of reasons which will not be discussed here. With the introduction of \iPhoneOS{ 3.2}, Apple now officially supports iPhone applications linking to the ICU library for the purpose of using its regular expression functionality.  This is encouraging news for \MacOSX{} developers if one assumes that Apple will try to keep some kind of parity between the \iPhoneOS{} and \MacOSX{} API's.

\subsection{iPhone OS < 3.2}

Prior to \iPhoneOS{ 3.2}, there was never any official support from Apple for linking to the \File{libicucore.dylib} library.  It was unclear if linking to the library would violate the \iPhoneOS{ SDK} Agreement prohibition against using undocumented API's, but a large number of iPhone applications choose to use \RegexKitLite{}, and the author is not aware of a single rejection because of it.

\subsection{iPhone OS ≥ 3.2}

Starting with \iPhoneOS{ 3.2}, Apple now officially allows \iPhoneOS{} applications to \RKLHref{http://developer.apple.com/iphone/library/releasenotes/General/WhatsNewIniPhoneOS/Articles/iPhoneOS3_2.html\#//apple_ref/doc/uid/TP40009337-SW25}{link with the ICU library}. The ICU library contains a lot of functionality for dealing with internationalization and localization, but \RKLHref{http://developer.apple.com/iphone/library/documentation/General/Conceptual/iPadProgrammingGuide/Text/Text.html\#//apple_ref/doc/uid/TP40009370-CH8-SW31}{Apple only officially permits the use of the ICU Regular Expression functionality}.

Apple also provides a way to use ICU based regular expressions from \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/ObjC\_classic/index.html}{Foundation} by adding a new option to \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html\#//apple_ref/c/tdef/NSStringCompareOptions}{NSStringCompareOptions}\textendash{} \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html\#//apple_ref/c/econst/NSRegularExpressionSearch}{NSRegularExpressionSearch}. This new option can be used with the \Code{NSString} \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html\#//apple_ref/occ/instm/NSString/rangeOfString:options:}{rangeOfString:options:} method, and the following example of its usage is given:

\begin{lstlisting}
// finds phone number in format nnn-nnn-nnnn
NSRange r;
NSString *regEx = @"[0-9]{3}-[0-9]{3}-[0-9]{4}";
r = [textView.text rangeOfString:regEx options:NSRegularExpressionSearch];
if (r.location != NSNotFound) {
    NSLog(@"Phone number is %@", [textView.text substringWithRange:r]);
} else {
    NSLog(@"Not found.");
}
\end{lstlisting}

At this time, \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html\#//apple_ref/occ/instm/NSString/rangeOfString:options:}{rangeOfString:options:} is the only regular expression functionality Apple has added to \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/ObjC\_classic/index.html}{Foundation} and capture groups in a regular expression are not supported.  Apple also gives the following note:

\RKLBoxNote{As noted in \RKLHref{http://developer.apple.com/iphone/library/documentation/General/Conceptual/iPadProgrammingGuide/Text/Text.html\#//apple_ref/doc/uid/TP40009370-CH8-SW31}{"ICU Regular-Expression Support,"} the ICU libraries related to regular expressions are included in \iPhoneOS{ 3.2}. However, you should only use the ICU facilities if the \Code{NSString} alternative is not sufficient for your needs.}

\RegexKitLite{} provides a much richer API, such as the automatic extraction of a match as a \Code{NSString}.  Using \RegexKitLite{}, the example can be rewritten as:

\begin{lstlisting}
// finds phone number in format nnn-nnn-nnnn
NSString *regEx = @"[0-9]{3}-[0-9]{3}-[0-9]{4}";
NSString *match = [textView.text stringByMatching:regEx];
if ([match isEqual:@""] == NO) {
    NSLog(@"Phone number is %@", match);
} else {
    NSLog(@"Not found.");
}
\end{lstlisting}

What's more, \RegexKitLite{} provides easy access to all the matches of a regular expression in a \Code{NSString}:

\begin{lstlisting}
// finds phone number in format nnn-nnn-nnnn
NSString *regEx = @"[0-9]{3}-[0-9]{3}-[0-9]{4}";
for(NSString *match in [textView.text componentsMatchedByRegex:regEx]) {
    NSLog(@"Phone number is %@", match);
}
\end{lstlisting}

To do the same thing using just \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html\#//apple_ref/c/econst/NSRegularExpressionSearch}{NSRegularExpressionSearch} would require significantly more code and effort on your part.  \RegexKitLite{} also provides powerful search and replace functionality:

\begin{lstlisting}
// finds phone number in format nnn-nnn-nnnn
NSString *regEx = @"([0-9]{3})-([0-9]{3}-[0-9]{4})";
// and transforms the phone number in to the format of (nnn) nnn-nnnn
NSString *replaced = [textView.text stringByReplacingOccurrencesOfRegex:regEx
                                                             withString:@"($1) $2"];
\end{lstlisting}

\RegexKitLite{} also has a number of performance enhancing features built in such as caching compiled regular expressions.  Although the author does not have any benchmarks comparing \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html\#//apple_ref/c/econst/NSRegularExpressionSearch}{NSRegularExpressionSearch} to \RegexKitLite{}, it is likely that \RegexKitLite{} outperforms \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html\#//apple_ref/c/econst/NSRegularExpressionSearch}{NSRegularExpressionSearch}.

\begin{RKLSeeAlso}
\item \RKLSectionHref{http://developer.apple.com/iphone/library/releasenotes/General/WhatsNewIniPhoneOS/Articles/iPhoneOS3_2.html\#//apple_ref/doc/uid/TP40009337-SW25}{What's New in iPhone OS - ICU Regular-Expression Support}
\item \RKLSectionHref{http://developer.apple.com/iphone/library/releasenotes/General/WhatsNewIniPhoneOS/Articles/iPhoneOS3_2.html\#//apple_ref/doc/uid/TP40009337-SW17}{What's New in iPhone OS - Foundation Framework Changes}
\item \RKLSectionHref{http://developer.apple.com/iphone/library/documentation/General/Conceptual/iPadProgrammingGuide/Text/Text.html\#//apple_ref/doc/uid/TP40009370-CH8-SW31}{iPad Programming Guide - ICU Regular-Expression Support}
\item \RKLSectionHref{http://developer.apple.com/iphone/library/documentation/General/Conceptual/iPadProgrammingGuide/Text/Text.html\#//apple_ref/doc/uid/TP40009370-CH8-SW33}{iPad Programming Guide - Foundation-Level Regular Expressions}
\item \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html\#//apple_ref/c/econst/NSRegularExpressionSearch}{NSRegularExpressionSearch}
\item \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/Reference/NSString.html\#//apple_ref/occ/instm/NSString/rangeOfString:options:}{- rangeOfString:options:}
\end{RKLSeeAlso}

\subsection{The iPhone 4.0 SDK Agreement}

While \iPhoneOS{ 3.2} included official, Apple sanctioned use of linking of the ICU library for the purposes of using the ICU regular expression engine, the \iPhoneOS{ 4.0 SDK} included the following change to the \iPhoneOS{ SDK} Agreement:

\begin{description}[topsep=-5.75pt, partopsep=\parskip, parsep=2.5pt, itemsep=0pt, font=\normalfont, leftmargin=*, rightmargin=1.75ex] %
  \item[3.3.1] Applications may only use Documented APIs in the manner prescribed by Apple and must not use or call any private APIs. Applications must be originally written in Objective-C, C, C++, or JavaScript as executed by the iPhone OS WebKit engine, and only code written in C, C++, and Objective-C may compile and directly link against the Documented APIs (e.g., Applications that link to Documented APIs through an intermediary translation or compatibility layer or tool are prohibited).
\end{description}

This raises a number of obvious questions:

\begin{RKLBulletList}
  \item Does 3.3.1 apply to \RegexKitLite{}?
  \item Will the use of \RegexKitLite{} in an \iPhoneOS{} application be grounds for rejection under 3.3.1?
\end{RKLBulletList}


There is considerable speculation as to what is covered by this change, but at the time of this writing, there is no empirical evidence or official guidelines from Apple to make any kind of an informed decision as to whether or not the use of \RegexKitLite{} would violate 3.3.1.  It is the authors opinion that \RegexKitLite{} could be considered as a \It{compatibility layer} between \Code{NSString} and the now \It{Documented APIs} for regular expressions in the ICU library.

It is widely speculated that the motivation for the change to 3.3.1 was to prevent the development of Flash applications for the iPhone.  The author believes that most reasonable people would consider the application of \It{compatibility layer} in this context to mean something entirely different than what it means when applied to \RegexKitLite{}.

At this time, the author is not aware of a single iPhone application that has been rejected due to the use of \RegexKitLite{}.  If your application is rejected due to the use of \RegexKitLite{}, please let the author know by emailing \RKLHref{mailto:regexkitlite@gmail.com}{\ConsoleText{regexkitlite@gmail.com}}.  As always, {\fontspec[Scale=1.08]{Courier}CAVEAT EMPTOR}.

\section{The Difference Between RegexKit.framework and \protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite}}

RegexKit.framework and \RegexKitLite{} are two different projects.  In retrospect, \RegexKitLite{} should have been given a more distinctive name.  Table-\ref*{table_rkf_rkl_diff} summarizes some of the key differences between the two.

\begin{table}[!h]
\caption{Differences between RegexKit.framework and \RegexKitLite{}\label{table_rkf_rkl_diff}}
\begin{tabularx}{\textwidth}{|Sl|SX|SX|}\hline
\rowcolor[gray]{0.8862745}  & \makecell[c{X}]{\Bd{RegexKit.framework}} & \makecell[c{X}]{\Bd{\RegexKitLite{}}}\\\hline
\Bd{Regex Library} & \makecell[c{X}]{PCRE} & \makecell[c{X}]{ICU}\\\hline
\Bd{Library Included} & \makecell[c{X}]{Yes, built into framework object file.} & \makecell[c{X}]{No, provided by \MacOSX{}.}\\\hline
\Bd{Library Linked As} & \makecell[c{X}]{Statically linked into framework.} & \makecell[c{X}]{\RaggedRight Dynamically linked to \linebreak \File{/usr/lib/libicucore.dylib.}}\\\hline
\Bd{Compiled Size} & \makecell[c{X}]{Approximately 371KB$^{\dag}$ per architecture.} & \makecell[c{X}]{Very small, approximately 16KB-20KB$^{\ddag}$ per architecture.}\\\hline
\Bd{Style} & \makecell[c{X}]{External, linked to framework.} & \makecell[c{X}]{Compiled directly in to final executable.}\\\hline
\Bd{Feature Set} & \makecell[c{X}]{Large, with additions to many classes.} & \makecell[c{X}]{Minimal, \Code{NSString} only.}\\\hline
\end{tabularx}
\end{table}

\begin{tabularx}{\textwidth}{lX}
\makecell[t]{$^{\dag}$} & \makecell[t{X}]{Version 0.6.0. About half of the 371KB is the PCRE library.\newline
The default distribution framework shared library file is 1.4MB in size and includes the \QuotedText{ppc}, \QuotedText{ppc64}, \QuotedText{i386}, and \QuotedText{x86\_64} architectures.\newline
If \HardNobr{64-bit} support is removed, the framework shared library file size drops to 664KB.}\\
\addlinespace[3pt]
\makecell[t]{$^{\ddag}$} & \makecell[t{X}]{Since the ICU library is part of \MacOSX{}, it does not add to the final size.}\\
\end{tabularx}


%  <div class="XXX">
%    Add PCRE vs. ICU regex differences.
%  </div>


\section{Compiled Regular Expression Cache}

The \Code{NSString} that contains the regular expression must be compiled in to an ICU \RKLCodeHref{http://www.icu-project.org/apiref/icu4c/uregex\_8h.html\#566882c83d9e4dcf7fb5d8f859625500}{URegularExpression}.  This can be an expensive, time consuming step, and the compiled regular expression can be reused again in another search, even if the strings to be searched are different.  Therefore \RegexKitLite{} keeps a small cache of recently compiled regular expressions.

The cache is organized as a \HardNobr{4-way} set associative cache, and the size of the cache can be tuned with the preprocessor define \CPPFlag{RKL\_CACHE\_SIZE}.  The default cache size, which should always be a prime number, is set to \Code{13}.  Since the cache is \HardNobr{4-way} set associative, the total number of compiled regular expressions that can be cached is \CPPFlag{RKL\_CACHE\_SIZE} times four, for a total of \Code{13 * 4}, or \Code{52}.  The \Code{NSString} \Argument{regexString} is mapped to a cache set using modular arithmetic: Cache set {\MnSymbolFont \char"2261} \Code{[regexString hash]} mod \CPPFlag{RKL\_CACHE\_SIZE}, i.e. \Code{cacheSet = [regexString hash] \% 13;}.  Since \RegexKitLite{} uses \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation}, this is actually coded  as \Code{cacheSet = CFHash(regexString) \% \Code{\BdIt{RKL\_CACHE\_SIZE}};}.

Each of the four "ways" of a cache set are checked to see if it contains a \Code{NSString} that was used to create the compiled regular expression that is identical to the \Code{NSString} for the regular expression that is being checked.  If there is an exact match, then the matching "way" is updated as the most recently used, and the compiled regular expression is used as-is.  Otherwise, the least recently used, or LRU, "way" in the cache set is cleared and replaced with the compiled regular expression for the regular expression that wasn't in the cache.

In addition to the compiled regular expression cache, \RegexKitLite{} keeps a small lookaside cache that maps a regular expressions \Code{NSString} pointer and \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} directly to a cached compiled regular expression. When a regular expressions \Code{NSString} pointer and \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} is in the lookaside cache, \RegexKitLite{} can bypass calling \Code{CFHash(regexString)} and checking each of the four "ways" in a cache set since the lookaside cache has provided the exact cached compiled regular expression.  The lookaside cache is quite small at just 64 bytes and it was added because \HardNobr{\File{Shark.app}} profiling during performance tuning showed that \Code{CFHash()}, while quite fast, was the primary bottleneck when retrieving already compiled and cached regular expressions, typically accounting for \textapproximatelyequalto{}40\% of the look up time.

\subsection{Regular Expressions in Mutable Strings}

When a regular expression is compiled, an immutable copy of the string is kept.  For immutable \Code{NSString} objects, the copy is usually the same object with its reference count increased by one.  Only \Code{NSMutableString} objects will cause a new, immutable \Code{NSString} to be created.

If the regular expression being used is stored in a \Code{NSMutableString}, the cached regular expression will continue to be used as long as the \Code{NSMutableString} remains unchanged.  Once mutated, the changed \linebreak \Code{NSMutableString} will no longer be a match for the cached compiled regular expression that was \linebreak being used by it previously.  Even if the newly mutated strings \Code{hash} is congruent to the previous \linebreak unmutated strings \Code{hash} modulo \CPPFlag{RKL\_CACHE\_SIZE}, that is to say they share the same cache set (i.e., \linebreak \Code{([mutatedString hash] \% \Code{\BdIt{RKL\_CACHE\_SIZE}}) == ([unmutatedString hash] \% \Code{\BdIt{RKL\_CACHE\_SIZE}}))}, the immutable copy of the regular expression string used to create the compiled regular expression is used to ensure true equality.  The newly mutated string will have to go through the whole regular expression compile and cache creation process.

This means that \Code{NSMutableString} objects can be safely used as regular expressions, and any mutations to those objects will immediately be detected and reflected in the regular expression used for matching.

\subsection{Searching Mutable Strings}

Unfortunately, the ICU regular expression API requires that the compiled regular expression be "set" to the string to be searched.  To search a different string, the compiled regular expression must be "set" to the new string.  Therefore, \RegexKitLite{} tracks the last \Code{NSString} that each compiled regular expression was set to, recording the pointer to the \Code{NSString} object, its hash, and its length.  If any of these parameters are different from the last parameters used for a compiled regular expression, the compiled regular expression is "set" to the new string.  Since mutating a string will likely change its \Code{hash} value, it's generally safe to search \Code{NSMutableString} objects, and in most cases the mutation will reset the compiled regular expression to the updated contents of the \Code{NSMutableString}.

\RKLBoxCaution{Care must be taken when mutable strings are searched and there exists the possibility that the string has mutated between searches.  See \RKLSectionPageRef{NSString_RegexKitLiteAdditions__CachedInformationandMutableStrings}{NSString \RegexKitLite{} Additions Reference - Cached Information and Mutable Strings} for more information.}

\subsection{Last Match Information}

When performing a match, the arguments used to perform the match are kept.  If those same arguments are used again, the actual matching operation is skipped because the compiled regular expression already contains the results for the given arguments.  This is mostly useful when a regular expression contains multiple capture groups, and the results for different capture groups for the same match are needed.  This means that there is only a small penalty for iterating over all the capture groups in a regular expression for a match, and essentially becomes the direct ICU regular expression API equivalent of \RKLHref{http://www.icu-project.org/apiref/icu4c/uregex\_8h.html\#5a2eccd52a16efe1ba99c53d56614a4f}{\HardNobr{\Code{uregex\_start()}}} and \RKLHref{http://www.icu-project.org/apiref/icu4c/uregex\_8h.html\#3f5e9eba75d943ff1aba3d3dc779a67f}{\HardNobr{\Code{uregex\_end()}}}.

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://www.icu-project.org/apiref/icu4c/uregex\_8h.html}{ICU4C C API - Regular Expressions}
  \item \RKLSectionPageRef{ICUSyntax_ICURegularExpressionSyntax}{ICU Regular Expression Syntax}
\end{RKLSeeAlso}

\section{\protect\texorpdfstring{\UTF{16}}{UTF-16} Conversion Cache}

\RegexKitLite{} is ideal when the string being matched is a non-\Code{ASCII}, Unicode string.  This is because the regular expression engine used, ICU, can only operate on \UTF{16} encoded strings.  Since Cocoa keeps essentially all non-\Code{ASCII} strings encoded in \UTF{16} form internally, this means that \RegexKitLite{} can operate directly on the strings buffer without having to make a temporary copy and transcode the string in to ICU's required format.

Like all object oriented programming, the internal representation of an objects information is private.  However, the ICU regular expression engine requires that the text to be search be encoded as a \UTF{16} string.  For pragmatic purposes, \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation} has several public functions that can provide direct access to the buffer used to hold the contents of the string, but such direct access is only available if the private buffer is already encoded in the requested direct access format.  As a rough rule of thumb, \HardNobr{8-bit} simple strings, such as \Code{ASCII}, are kept in their \HardNobr{8-bit} format.  Non \HardNobr{8-bit} simple strings are stored as \UTF{16} strings.  Of course, this is an implementation private detail, so this behavior should never be relied upon.  It is mentioned because of the tremendous impact on matching performance and efficiency it can have if a string must be converted to \UTF{16}.

For strings in which direct access to the \UTF{16} string is available, \RegexKitLite{} uses that buffer.  This is the ideal case as no extra work needs to be performed, such as converting the string in to a \UTF{16} string, and allocating memory to hold the temporary conversion.  Of course, direct access is not always available, and occasionally the string to be searched will need to be converted in to a \UTF{16} string.

\RegexKitLite{} has two conversion cache types. Each conversion cache type contains four buffers each, and buffers are re-used on a least recently used basis.  If the selected cache type does not contain the contents of the \Code{NSString} that is currently being searched in any of its buffers, the least recently used buffer is cleared and the current \Code{NSString} takes it place.  The first conversion cache type is fixed in size and set by the C preprocessor define \CPPFlag{RKL\_FIXED\_LENGTH}, which defaults to \Code{2048}.  Any string whose length is less than \CPPFlag{RKL\_FIXED\_LENGTH} will use the fixed size conversion cache type.  The second conversion cache type, for strings whose length is longer than \CPPFlag{RKL\_FIXED\_LENGTH}, will use a dynamically sized conversion buffer.  The memory allocation for the dynamically sized conversion buffer is resized for each conversion with \HardNobr{\Code{realloc()}} to the size needed to hold the entire contents of the \UTF{16} converted string.

This strategy was chosen for its relative simplicity.  Keeping track of dynamically created resources is required to prevent memory leaks.  As designed, there are only four pointers to dynamically allocated memory: the four pointers to hold the conversion contents of strings whose length is larger than \CPPFlag{RKL\_FIXED\_LENGTH}.  However, since \Code{realloc()} is used to manage those memory allocations, it becomes very difficult to accidentally leak the buffers.  Having the fixed sized buffers means that the memory allocation system isn't bothered with many small requests, most of which are transient in nature to begin with.  The current strategy tries to strike the best balance between performance and simplicity.

\subsection{Mutable Strings}

When converted in to a \UTF{16} string, the \Code{hash} of the \Code{NSString} is recorded, along with the pointer to the \Code{NSString} object and the strings length.  In order for the \RegexKitLite{} to use the cached conversion, all of these parameters must be equal to their values of the \Code{NSString} to be searched.  If there is any difference, the cached conversion is discarded and the current \Code{NSString}, or \Code{NSMutableString} as the case may be, is reconverted in to a \UTF{16} string.

\RKLBoxCaution{Care must be taken when mutable strings are searched and there exists the possibility that the string has mutated between searches.  See \RKLSectionPageRef{NSString_RegexKitLiteAdditions__CachedInformationandMutableStrings}{NSString \RegexKitLite{} Additions Reference - Cached Information and Mutable Strings} for more information.}

\section{Multithreading Safety}

\RegexKitLite{} is also multithreading safe.  Access to the compiled regular expression cache and the conversion cache is protected by a single \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man3/spinlock.3.html}{OSSpinLock} to ensure that only one thread has access at a time.  The lock remains held while the regular expression match is performed since the compiled regular expression returned by the ICU library is not safe to use from multiple threads.  Once the match has completed, the lock is released, and another thread is free to lock the cache and perform a match.

\RKLBoxImportant{While it is safe to use the same regular expression from any thread at any time, the usual multithreading caveats apply.  For example, it is not safe to mutate a \Code{NSMutableString} in one thread while performing a match on the mutating string in another.}

If Blocks functionality is enabled, and a \RegexKitLite{} method that takes a Block as one of its parameters is used, \RegexKitLite{} takes a slightly different approach in order to support the asynchronous, and possibly re-entrant, nature of Blocks.

First, an autoreleased Block helper proxy object is created and is used to keep track of any Block local resources needed to perform a Block-based enumeration. 

Then the regular expression cache is checked exactly as before. Once a compiled regular expression is obtained, the ICU function \RKLCodeHref{http://icu-project.org/apiref/icu4c/uregex_8h.html\#a3befb11b7c9b28c19af6114ed19b7339}{uregex\_clone} is used to create a Block local copy of the regular expression. After the Block local copy has been made, the global compiled regular expression cache lock is unlocked.

If the string to be searched requires conversion to \UTF{16}, then a one time use Block local \UTF{16} conversion of the string is created.

These changes mean that \RegexKitLite{} Block-based enumeration methods are just as multithreading safe and easy to use as non-Block-based enumeration methods, such as the ability to continue to use \RegexKitLite{} methods without any restrictions from within the Block used for enumeration.

\section{64-bit Support}

\RegexKitLite{} is \HardNobr{64-bit} clean.  Internally, \RegexKitLite{} uses Cocoas standard \Code{NSInteger} and \Code{NSUInteger} types for representing integer values.  The size of these types change between \HardNobr{32-bit} and \HardNobr{64-bit} automatically, depending on the target architecture.  ICU, on the other hand, uses a signed \HardNobr{32-bit} \Code{int} type for many of its arguments, such as string offset values. Because of this, the maximum length of a string that \RegexKitLite{} will accept is the maximum value that can be represented by a signed \HardNobr{32-bit} integer, which is approximately 2 gigabytes.  Strings that are longer this limit will raise \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSRangeException}{NSRangeException}. This limitation may be significant to those who are switching to \HardNobr{64-bit} because the size of the data they need to process exceeds what can be represented with \HardNobr{32-bits.}

\RKLBoxNote{Several numeric constants throughout this document will have either \Code{L} or \Code{UL} appended to them\textendash{} for example \Code{0UL}, or \Code{2L}.  This is to ensure that they are treated as \HardNobr{64-bit} \Code{long} or \linebreak \Code{unsigned long} values, respectively, when targeting a \HardNobr{64-bit} architecture.}


\labeledchapter{UsingRegexKitLite}{Using \protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite}}

The goal of \RegexKitLite{} is not to be a comprehensive \ObjectiveC{} regular expression framework, but to provide a set of easy to use primitives from which additional functionality can be created.  To this end, \RegexKitLite{} provides the following two core primitives from which everything else is built:

\vskip 0pt plus 1pt minus 1pt
\begin{RKLBulletList}
  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Selector{captureCountWithOptions:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options}\\~~~~\Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Selector{rangeOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options}\\~~~~\Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{capture:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Argument{capture} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}}

\end{RKLBulletList}

There is often a need to create a new string of the characters that were matched by a regular expression.  \RegexKitLite{} provides the following method which conveniently combines sending the receiver \linebreak \Code{substringWithRange:} with the range returned by \Code{rangeOfRegex:}.



\vskip 0pt plus 1pt minus 1pt
\begin{RKLBulletList}
  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByMatching:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options}\\~~~~\Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{capture:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Argument{capture} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}}
\end{RKLBulletList}


\RegexKitLite{ 2.0} adds the ability to split strings by dividing them with a regular expression, and \linebreak the ability to perform search and replace operations using common \Regex{\$}\Argument{n} substitution syntax. \linebreak \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:}{replaceOccurrencesOfRegex:withString:} is used to modify the contents of \Code{NSMutableString} objects directly and \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:}{stringByReplacingOccurrencesOfRegex:withString:} will create a new, immutable \Code{NSString} from the receiver.


\vskip 0pt plus 1pt minus 1pt
\begin{RKLBulletList}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{componentsSeparatedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSUInteger}{NSUInteger})\Selector{replaceOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{withString:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{replacement}\\~~~~\Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByReplacingOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{withString:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{replacement}\\~~~~\Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}}

\end{RKLBulletList}


\RegexKitLite{ 3.0} adds several new methods that return a \Code{NSArray} containing the aggregated results of a number of individual regex operations.


\vskip 0pt plus 1pt minus 1pt
\begin{RKLBulletList}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{arrayOfCaptureComponentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{captureComponentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{componentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range};}}

\end{RKLBulletList}

%\vfil
\pagebreak

\RegexKitLite{ 4.0} adds several new methods that take advantage of the new blocks language extension.


\begin{RKLBulletList}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{enumerateStringsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{usingBlock:}(void (\textasciicircum{})(\\~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount}, \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount], volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{enumerateStringsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error}\\~~~~\Selector{enumerationOptions:}(\RKLCodeRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions})\Argument{enumerationOptions}\\~~~~\Selector{usingBlock:}(void (\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount], volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{enumerateStringsSeparatedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{usingBlock:}(void (\textasciicircum{})(\\~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount}, \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount], volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{enumerateStringsSeparatedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error}\\~~~~\Selector{enumerationOptions:}(\RKLCodeRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions})\Argument{enumerationOptions}\\~~~~\Selector{usingBlock:}(void (\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount], volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByReplacingOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{usingBlock:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *(\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount], volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByReplacingOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error}\\~~~~\Selector{enumerationOptions:}(\RKLCodeRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions})\Argument{enumerationOptions}\\~~~~\Selector{usingBlock:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *(\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount], volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSUInteger}{NSUInteger})\Selector{replaceOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{usingBlock:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *(\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount], volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}}

  \item {\RaggedRight \SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSUInteger}{NSUInteger})\Selector{replaceOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error}\\~~~~\Selector{enumerationOptions:}(\RKLCodeRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions})\Argument{enumerationOptions}\\~~~~\Selector{usingBlock:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *(\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount], volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}}

\end{RKLBulletList}

There are no additional classes that supply the regular expression matching functionality, everything is accomplished with the two methods above.  These methods are added to the existing \Code{NSString} class via an \ObjectiveC{} category extension.  See \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference}{\RegexKitLite{} \Code{NSString} Additions Reference} for a complete list of methods.

The real workhorse is the \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:}{rangeOfRegex:options:inRange:capture:error:} method.  The receiver of the message is an ordinary \Code{NSString} class member that you wish to perform a regular expression match on.  The parameters of the method are a \Code{NSString} containing the regular expression \Argument{regex}, any \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} match \Argument{options}, the \Code{NSRange} \Argument{range} of the receiver that is to be searched, the \Argument{capture} number from the regular expression \Argument{regex} that you would like the result for, and an optional \Argument{error} parameter that will contain a \Code{NSError} object if a problem occurs with the details of the error.

\RKLBoxImportant{The C language assigns special meaning to the \ConsoleText{\textbackslash{}} character when inside a quoted \ConsoleText{"~"} string in your source code.  The \ConsoleText{\textbackslash{}} character is the escape character, and the character that follows has a different meaning than normal.  The most common example of this is \ConsoleText{\textbackslash{}n}, which translates in to the \RegexDef{new-line} character.  Because of this, you are required to 'escape' any uses of \ConsoleText{\textbackslash{}} by prepending it with another \ConsoleText{\textbackslash{}}.  In practical terms this means doubling any \ConsoleText{\textbackslash{}} in a regular expression, which unfortunately is quite common, that are inside of quoted \ConsoleText{"~"} strings in your source code. Failure to do so will result in numerous warnings from the compiler about unknown escape sequences. To match a single literal \ConsoleText{\textbackslash{}} with a regular expression requires no less than four backslashes: \ConsoleText{"\textbackslash{}\textbackslash{}\textbackslash{}\textbackslash{}"}.}

\begin{RKLSeeAlso}
  \item \RKLSectionPageRef{ICUSyntax_ICURegularExpressionSyntax}{ICU Regular Expression Syntax}
  \item \RKLSectionPageRef{RegexKitLiteCookbook}{\RegexKitLite{} Cookbook}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference}{\RegexKitLite{} \Code{NSString} Additions Reference}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}%
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
\end{RKLSeeAlso}

\section{Finding the Range of a Match}

A simple example:

\begin{lstlisting}
NSString *searchString = @"This is neat.";
NSString *regexString  = @"(\\w+)\\s+(\\w+)\\s+(\\w+)";
NSRange   matchedRange = NSMakeRange(NSNotFound, 0UL);
NSError  *error        = NULL;

matchedRange = [searchString rangeOfRegex:regexString
                                  options:RKLNoOptions
                                  inRange:searchRange
                                  capture:2L
                                    error:&error];

NSLog(@"matchedRange: %@", NSStringFromRange(matchedRange));
// 2008-03-18 03:51:16.530 test[51583:813] matchedRange: {5, 2}
\end{lstlisting}
%</span></div><div class="metainfo bottom noPrintBorder"><span class="entry continues below"><span class="item meta">Continues\textellipsis{}</span></span></div><div class="floatRightPadder noSelect"> </div></div>

In the previous example, the \Code{NSRange} that capture number \Code{2} matched is \Code{\{5, 2\}}, which corresponds to the word \QuotedText{is} in \Code{searchString}.  Once the \Code{NSRange} is known, you can create a new string containing just the matching text:

%<div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">\textellipsis{}example</span></span></div><div>
\begin{lstlisting}
NSString *matchedString = [searchString substringWithRange:matchedRange];

NSLog(@"matchedString: '%@'", matchedString);
// 2008-03-18 03:51:16.532 test[51583:813] matchedString: 'is'
\end{lstlisting}

\RegexKitLite{} can conveniently combine the two steps above with \Code{stringByMatching:}.  This example also demonstrates the use of one of the simpler convenience methods, where some of the arguments are automatically filled in with default values:

\begin{lstlisting}
NSString *searchString  = @"This is neat.";
NSString *regexString   = @"(\\w+)\\s+(\\w+)\\s+(\\w+)";

NSString *matchedString = [searchString stringByMatching:regexString capture:2L];

NSLog(@"matchedString: '%@'", matchedString);
// 2008-03-18 03:53:42.949 test[51583:813] matchedString: 'is'
\end{lstlisting}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:}{- rangeOfRegex:}%
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:}{- stringByMatching:}%
  \item \RKLSectionPageRef{ICUSyntax_ICURegularExpressionSyntax}{ICU Regular Expression Syntax}
\end{RKLSeeAlso}

\section{Search and Replace}

You can perform search and replace operations on \Code{NSString} objects and use common \Regex{\$}\Argument{n} capture group substitution in the replacement string:

\begin{lstlisting}
NSString *searchString      = @"This is neat.";
NSString *regexString       = @"\\b(\\w+)\\b";
NSString *replaceWithString = @"{$1}";
NSString *replacedString    = NULL;

replacedString = [searchString stringByReplacingOccurrencesOfRegex:regexString 
                                                        withString:replaceWithString];

NSLog(@"replaced string: '%@'", replacedString);
// 2008-07-01 19:03:03.195 test[68775:813] replaced string: '{This} {is} {neat}.'
\end{lstlisting}

\RKLBoxImportant{Search and replace methods will raise a \RKLCodePageRef{RKLICURegexException}{RKLICURegexException} if the \HardNobr{\Argument{replacementString}} contains \Regex{\$}\Argument{n} capture references where \Argument{n} is greater than the number of capture groups in the regular expression.}

In this example, the regular expression \Regex{\textbackslash{}b(\textbackslash{}w+)\textbackslash{}b} has a single capture group, which is created with the use of \Regex{()} parenthesis.  The text that was matched inside the parenthesis is available for use in the replacement text by using \Regex{\$}\Argument{n}, where \Argument{n} is the parenthesized capture group you would like to use.  Additional capture groups are numbered sequentially in the order that they appear from left to right.  Capture group \ConsoleText{0} (zero) is also available and is equivalent to all the text that the regular expression matched.

Mutable strings can be manipulated directly:

\begin{lstlisting}
NSString        *regexString       = @"\\b(\\w+)\\b";
NSString        *replaceWithString = @"{$1}";
NSUInteger       replacedCount     = 0UL;

NSMutableString *mutableString = [NSMutableString stringWithString:@"This is neat."];

replacedCount = [mutableString replaceOccurrencesOfRegex:regexString
                                              withString:replaceWithString];

NSLog(@"count: %lu string: '%@'", (u_long)replacedCount, mutableString);
// 2008-07-01 21:25:43.433 test[69689:813] count: 3 string: '{This} {is} {neat}.'
\end{lstlisting}

\subsection{Search and Replace using Blocks}

\RegexKitLite{ 4.0} adds support for performing the same search and replacement on strings, except now the contents of the replacement string are created by the Block that is passed as the argument.  For each match that is found in the string, the Block argument is called and passed the details of the match which includes a C array of \Code{NSString} objects, one for each capture, along with a C array of \Code{NSRange} structures with the range information for the current match.

The text that was matched will be replaced with the \Code{NSString} object that the Block is required to return. %
This allows you complete control over the contents of the replaced text, such as doing complex transformations of the matched text, which is much more flexible and powerful than the simple, fixed replacement functionality provided by \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:}{stringByReplacingOccurrencesOfRegex:withString:}.

The example below is essentially the same as the previous search and replace examples, except this example uses the \Code{capitalizedString} method to capitalize the matched result, which is then used in the string that is returned as the replacement text.  Note that the first letter in each word in \Code{replacedString} is now capitalized.

\begin{lstlisting}
NSString *searchString      = @"This is neat.";
NSString *regexString       = @"\\b(\\w+)\\b";
NSString *replacedString    = NULL;

replacedString = [searchString stringByReplacingOccurrencesOfRegex:regexString
                                                        usingBlock:
                  ^NSString *(NSInteger captureCount,
                              NSString * const capturedStrings[captureCount],
                              const NSRange capturedRanges[captureCount],
                              volatile BOOL * const stop) {
                    return([NSString stringWithFormat:@"{%@}",
                            [capturedStrings[1] capitalizedString]]);
                  }];

// 2010-04-14 21:00:42.726 test[35053:a0f] replaced string: '{This} {Is} {Neat}.'
\end{lstlisting}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:}{- replaceOccurrencesOfRegex:usingBlock:}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:}{- replaceOccurrencesOfRegex:withString:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:}{- stringByReplacingOccurrencesOfRegex:usingBlock:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:}{- stringByReplacingOccurrencesOfRegex:withString:}
  \item \RKLSectionPageRef{ICUSyntax_ICURegularExpressionSyntax}{ICU Regular Expression Syntax}
  \item \RKLSectionPageRef{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax}
\end{RKLSeeAlso}



\section{Splitting Strings}

Strings can be split with a regular expression using the \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{componentsSeparatedByRegex:} methods.  This functionality is nearly identical to the preexisting \Code{NSString} method \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html\#//apple\_ref/occ/instm/NSString/componentsSeparatedByString:}{componentsSeparatedByString:}, except instead of only being able to use a fixed string as a separator, you can use a regular expression:

\begin{lstlisting}
NSString *searchString = @"This is neat.";
NSString *regexString  = @"\\s+";
NSArray  *splitArray   = NULL;

splitArray = [searchString componentsSeparatedByRegex:regexString];
// splitArray == { @"This", @"is", @"neat." }

NSLog(@"splitArray: %@", splitArray);
\end{lstlisting}
%</div><div class="metainfo bottom noPrintBorder"><span class="entry continues below"><span class="item meta">Continues\textellipsis{}</span></span></div><div class="floatRightPadder noSelect"> </div></div>

The output from \Code{NSLog()} when run from a shell:

%<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">\textellipsis{}</span><span class="item info">splitArray</span></span></div><span class="shellOutput">
\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{./splitArray}\ReturnKey{}
2008-07-01 20:58:39.025 splitArray[69618:813] splitArray: (
    This,
    is,
    "neat."
)
shell% \ShellCursor{}
\end{Verbatim}

Unfortunately our example string \Code{@"This\textvisiblespace{}is\textvisiblespace{}neat."} doesn't allow us to show off the power of regular expressions.  As you can probably imagine, splitting the string with the regular expression \Regex{\textbackslash{}s+} allows for one or more \RKLPageRef{ICUSyntax_ICURegularExpressionSyntax_white_space}{\RegexDef{white space}} characters to be matched.  This can be much more flexible than just a fixed string of \Code{@"\textvisiblespace{}"}, which will split on a single space only.  If our example string contained extra spaces, say \Code{@"This\textvisiblespace{}\textvisiblespace{}\textvisiblespace{}is\textvisiblespace{}\textvisiblespace{}\textvisiblespace{}\textvisiblespace{}\textvisiblespace{}neat."}, the result would have been the same.

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{- componentsSeparatedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:usingBlock:}{- enumerateStringsSeparatedByRegex:usingBlock:}
  \item \RKLSectionPageRef{ICUSyntax_ICURegularExpressionSyntax}{ICU Regular Expression Syntax}
\end{RKLSeeAlso}

\section{Creating an Array of Every Match}

\RegexKitLite{ 3.0} adds several methods that conveniently perform a number of individual \RegexKitLite{} operations and aggregate the results in to a \Code{NSArray}.  Since the result is a \Code{NSArray}, the standard Cocoa collection enumeration patterns can be used, such as \Code{NSEnumerator} and Objective-C 2.0's \Code{for\textellipsis{}in} feature.  One of the most common tasks is to extract all of the matches of a regular expression from a string. \linebreak \Code{componentsMatchedByRegex:} returns the entire text matched by a regular expression even if the regular expression contains additional capture groups, effectively capture group \Code{0}. For example:

\begin{lstlisting}
NSString *searchString = @"$10.23, $1024.42, $3099";
NSString *regexString  = @"\\$((\\d+)(?:\\.(\\d+)|\\.?))";
NSArray  *matchArray   = NULL;

matchArray = [searchString componentsMatchedByRegex:regexString];

// matchArray == { @"$10.23", @"$1024.42", @"$3099" };

NSLog(@"matchArray: %@", matchArray);
\end{lstlisting}

The output from \Code{NSLog()} when run from a shell:

%<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">\textellipsis{}</span><span class="item info">matchArray</span></span></div><span class="shellOutput">
\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{./matchArray}\ReturnKey{}
2009-05-06 03:20:03.546 matchArray[69939:10b] matchArray: (
    "$10.23",
    "$1024.42",
    "$3099"
)
shell% \ShellCursor{}
\end{Verbatim}

As the example above demonstrates, \Code{componentsMatchedByRegex:} returns the entire text that the \linebreak regular expression matched even though the regular expression contains capture groups. \linebreak \Code{arrayOfCaptureComponentsMatchedByRegex:} can be used if you need to get the text that the individual capture groups matched as well:

\begin{lstlisting}
NSString *searchString  = @"$10.23, $1024.42, $3099";
NSString *regexString   = @"\\\$((\\d+)(?:\\.(\\d+)|\\.?))";
NSArray  *capturesArray = NULL;

capturesArray = [searchString arrayOfCaptureComponentsMatchedByRegex:regexString];

/* capturesArray ==
[NSArray arrayWithObjects:
  [NSArray arrayWithObjects:  @"$10.23",   @"10.23",   @"10", @"23", NULL],
  [NSArray arrayWithObjects:@"$1024.42", @"1024.42", @"1024", @"42", NULL],
  [NSArray arrayWithObjects:   @"$3099",    @"3099", @"3099",   @"", NULL],
  NULL];
*/

NSLog(@"capturesArray: %@", capturesArray);
\end{lstlisting}
%</div><div class="metainfo bottom noPrintBorder"><span class="entry continues below"><span class="item meta">Continues\textellipsis{}</span></span></div><div class="floatRightPadder noSelect"> </div></div>

The output from \Code{NSLog()} when run from a shell:

%<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">\textellipsis{}</span><span class="item info">capturesArray</span></span></div><span class="shellOutput">
\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{./capturesArray}\ReturnKey{}
2009-05-06 03:25:46.852 capturesArray[69981:10b] capturesArray: (
        (
        "$10.23",
        "10.23",
        10,
        23
    ),
        (
        "$1024.42",
        "1024.42",
        1024,
        42
    ),
        (
        "$3099",
        3099,
        3099,
        ""
    )
)
shell% \ShellCursor{}
\end{Verbatim}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:}{- arrayOfCaptureComponentsMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:}{- captureComponentsMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:}{- componentsMatchedByRegex:}
  \item \RKLSectionPageRef{UsingRegexKitLite_EnumeratingMatches}{Enumerating Matches}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Collections/Articles/Enumerators.html}{Collections Programming Topics for Cocoa - Enumerators: Traversing a Collection's Elements}
\end{RKLSeeAlso}


\labeledsection{UsingRegexKitLite_EnumeratingMatches}{Enumerating Matches}

The \RegexKitLite{} \Code{componentsMatchedByRegex:} method enables you to quickly create a \Code{NSArray} containing all the matches of a regular expression in a string.  To enumerate the contents of the \Code{NSArray}, you can send the array an \Code{objectEnumerator} message.

An example using \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{componentsSeparatedByRegex:} and a \Code{NSEnumerator}:

%<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">main.m</span></span></div>
\begin{lstlisting}
#import <Foundation/Foundation.h>
#import "RegexKitLite.h"

int main(int argc, char *argv[]) {
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  NSString     *searchString    = @"one\ntwo\n\nfour\n";
  NSArray      *matchArray      = NULL;
  NSEnumerator *matchEnumerator = NULL;
  NSString     *regexString     = @"(?m)^.*$";
  NSString     *matchedString   = NULL;
  NSUInteger    line            = 0UL;

  NSLog(@"searchString: '%@'", searchString);
  NSLog(@"regexString : '%@'", regexString);

  matchArray      = [searchString componentsMatchedByRegex:regexString];
  matchEnumerator = [matchArray objectEnumerator];

  while((matchedString = [matchEnumerator nextObject]) != NULL) {
    NSLog(@"%lu: %lu '%@'", ++line, [matchedString length], matchedString);
  }

  [pool release];
  return(0);
}
\end{lstlisting}

The following shell transcript demonstrates compiling the example and executing it.  Line number three clearly demonstrates that matches of zero length are possible.  Without the additional logic in \Code{nextObject} to handle this special case, the enumerator would never advance past the match.

\RKLBoxNote{In the shell transcript below, the \Code{NSLog()} line that prints \Code{searchString} has been annotated with the '\ReturnSymbol{}' glyph to help visually identify the corresponding \Regex{\textbackslash{}n} \RegexDef{new-line} characters in \Code{searchString}.}

\label{UsingRegexKitLite_enumeratingMatches_exampleShellOutput}
\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{gcc -g -o match match RegexKitLite.m -framework Foundation -licucore}\ReturnKey{}
shell% \Bd{./match}\ReturnKey{}
2008-03-21 15:56:17.469 match[44050:807] searchString: 'one\ReturnSymbol{}
two\ReturnSymbol{}
\ReturnSymbol{}
four\ReturnSymbol{}
'
2008-03-21 15:56:17.520 match[44050:807] regexString : '(?m)^.*$'
2008-03-21 15:56:17.575 match[44050:807] 1: 3 'one'
2008-03-21 15:56:17.580 match[44050:807] 2: 3 'two'
2008-03-21 15:56:17.584 match[44050:807] 3: 0 "
2008-03-21 15:56:17.590 match[44050:807] 4: 4 'four'
shell% \ShellCursor{}
\end{Verbatim}

\subsection{Enumerating Matches with Objective-C 2.0}

You can enumerate all the matches of a regular expression in a string using Objective-C 2.0's \Code{for\textellipsis{}in} feature.  Compared to using a \Code{NSEnumerator}, using \Code{for\textellipsis{}in} not only takes fewer lines of code to accomplish the same thing, it is usually faster as well.

An example using the Objective-C 2.0 \Code{for\textellipsis{}in} feature:

%<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">for\_in.m</span></span></div>
\begin{lstlisting}
#import <Foundation/Foundation.h>
#import "RegexKitLite.h"

int main(int argc, char *argv[]) {
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  NSString   *searchString = @"one\ntwo\n\nfour\n";
  NSString   *regexString  = @"(?m)^.*$";
  NSUInteger  line         = 0UL;

  NSLog(@"searchString: '%@'", searchString);
  NSLog(@"regexString : '%@'", regexString);

  for(NSString *matchedString in [searchString componentsMatchedByRegex:regexString]) {
    NSLog(@"%lu: %lu '%@'", ++line, [matchedString length], matchedString);
  }

  [pool release];
  return(0);
}
\end{lstlisting}

\RKLBoxNote{The output of the preceding example is identical to the \Code{NSEnumerator} \RKLPageRef{UsingRegexKitLite_enumeratingMatches_exampleShellOutput}{shell output}.}

\subsection{Enumerating Matches using Blocks}

%You can enumerate all the matches of a regular expression in a string using Objective-C 2.0's \Code{for\textellipsis{}in} feature.  Compared to using a \Code{NSEnumerator}, using \Code{for\textellipsis{}in} not only takes fewer lines of code to accomplish the same thing, it is usually faster as well.

%An example using the Objective-C 2.0 \Code{for\textellipsis{}in} feature:

A third way to enumerate all the matches of a regular expression in a string is to use one of the Blocks-based enumeration methods.

An example using \RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:}{enumerateStringsMatchedByRegex:usingBlock:}:

%<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">for\_in.m</span></span></div>
\begin{lstlisting}
#import <Foundation/Foundation.h>
#import "RegexKitLite.h"

int main(int argc, char *argv[]) {
  NSAutoreleasePool  *pool = [[NSAutoreleasePool alloc] init];

          NSString   *searchString = @"one\ntwo\n\nfour\n";
          NSString   *regexString  = @"(?m)^.*$";
  __block NSUInteger  line         = 0UL;
  
  NSLog(@"searchString: '%@'", searchString);
  NSLog(@"regexString : '%@'", regexString);
  
  [searchString enumerateStringsMatchedByRegex:regexString
                                    usingBlock:
   ^(NSInteger captureCount,
     NSString * const capturedStrings[captureCount],
     const NSRange capturedRanges[captureCount],
     volatile BOOL * const stop) {
     NSLog(@"%lu: %lu '%@'", ++line, [capturedStrings[0] length], capturedStrings[0]);
   }];

  [pool release];
  return(0);
}
\end{lstlisting}

\RKLBoxNote{The output of the preceding example is identical to the \Code{NSEnumerator} \RKLPageRef{UsingRegexKitLite_enumeratingMatches_exampleShellOutput}{shell output}.}


\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:}{- componentsMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:}{- enumerateStringsMatchedByRegex:usingBlock:}
  \item \RKLSectionPageRef{RegularExpressionEnumerationOptions}{Regular Expression Enumeration Options}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{\RegexKitLite{} NSString Additions Reference - Block-based Enumeration Methods}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray Class Reference}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSEnumerator\_Class/Reference/Reference.html}{NSEnumerator Class Reference}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Collections/Articles/Enumerators.html}{Collections Programming Topics for Cocoa - Enumerators: Traversing a Collection's Elements}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/ObjectiveC/Articles/ocFastEnumeration.html}{The Objective-C 2.0 Programming Language - Fast Enumeration}
\end{RKLSeeAlso}

\labeledsection{UsingRegexKitLite_DTrace}{DTrace}

\RKLBoxImportant{DTrace support is not enabled by default.  To enable DTrace support, use the \CPPFlag{RKL\_DTRACE} preprocessor flag: \ConsoleText{-DRKL\_DTRACE}}

\RegexKitLite{} has two DTrace probe points that provide information about its internal caches:

\begin{RKLBulletList}
  \item \Code{\RaggedRight{}\Bd{RegexKitLite:::compiledRegexCache}(unsigned long \Argument{eventID}, const char *\Argument{regexUTF8},\\~~~~int \Argument{options}, int \Argument{captures}, int \Argument{hitMiss}, int \Argument{icuStatusCode},\\~~~~const char *\Argument{icuErrorMessage}, double *\Argument{hitRate});}
  \item \Code{\RaggedRight{}\Bd{RegexKitLite:::utf16ConversionCache}(unsigned long \Argument{eventID},\\~~~~unsigned int \Argument{lookupResultFlags}, double *\Argument{hitRate}, const void *\Argument{string},\\~~~~unsigned long \Argument{NSRange\_location}, unsigned long \Argument{NSRange\_length}, long \Argument{length});}
\end{RKLBulletList}

Each of the probe points supply information via a number of arguments that are accessible through the DTrace variables \Code{arg0} \textellipsis{} \Code{arg}\Argument{n}.

The first argument, \Argument{eventID} via \Code{arg0}, is a unique event ID that is incremented each time the \RegexKitLite{} mutex lock is acquired.  All the probes that fire while the mutex is held will share the same event ID.  This can help if you are trying to correlate multiple events across different CPUs.

\RKLBoxImportant{Most uses of the \ConsoleText{dtrace} command require superuser privileges.  The examples given here use \ConsoleText{sudo} to execute \ConsoleText{dtrace} as the \ConsoleText{root} user.}

The following is available in \File{examples/compiledRegexCache.d} and demonstrates the use of all the arguments available via the \Code{RegexKitLite:::compiledRegexCache} probe point:

%<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">compiledRegexCache.d</span></span></div>
\begin{lstlisting}
#!/usr/sbin/dtrace -s

RegexKitLite*:::compiledRegexCache {
  this->eventID         = (unsigned long)arg0;
  this->regexUTF8       = copyinstr(arg1);
  this->options         = (unsigned int)arg2;
  this->captures        = (int)arg3;
  this->hitMiss         = (int)arg4;
  this->icuStatusCode   = (int)arg5;
  this->icuErrorMessage = (arg6 == 0) ? "" : copyinstr(arg6);
  this->hitRate         = (double *)copyin(arg7, sizeof(double));

  printf("%5d: %-60.60s Opt: %# 8.8x Cap: %2d Hit: %2d Rate: %6.2f%% code: %5d msg: %s\n",
         this->eventID,
         this->regexUTF8,
         this->options,
         this->captures,
         this->hitMiss,
         *this->hitRate,
         this->icuStatusCode,
         this->icuErrorMessage);
}
\end{lstlisting}

Below is an example of the output from \File{compiledRegexCache.d}:

\RKLBoxNote{The output below has been significantly trimmed and altered to fit on a printed page.}
\vskip-\parskip\vskip-1em
%%<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">\textellipsis{}</span><span class="item info">compiledRegexCache.d</span></span></div><span class="shellOutput">
%\begin{Verbatim}[commandchars=\\\{\}]
%shell% \Bd{sudo dtrace -Z -q -s compiledRegexCache.d}\ReturnKey{}
%  110: (\textbackslash{}[\{2\})(.+?)(]\{2\})                                           Opt: 0x00000000 Cap:  3 Hit:  0 Rate:  63.64% code:     0 msg: 
%  111: (\textbackslash{}[\{2\})(.+?)(]\{2\})                                           Opt: 0x00000000 Cap:  3 Hit:  1 Rate:  63.96% code:     0 msg: 
%  131: (\textbackslash{}w+                                                         Opt: 0x00000000 Cap: -1 Hit: -1 Rate:  63.36% code: 66310 msg: U\_REGEX\_MISMATCHED\_PAREN
%  164: \textbackslash{}b\textbackslash{}s*                                                        Opt: 0x00000000 Cap:  0 Hit:  0 Rate:  60.98% code:     0 msg: 
%  165: \textbackslash{}$((\textbackslash{}d+)(?:\textbackslash{}.(\textbackslash{}d+)|\textbackslash{}.?))                                     Opt: 0x00000000 Cap:  3 Hit:  1 Rate:  61.21% code:     0 msg: 
%  166: \textbackslash{}b(https?)://([a-zA-Z0-9\textbackslash{}-.]+)((?:/[a-zA-Z0-9\textbackslash{}-._?,'+\textbackslash{}&%$\textellipsis{}   Opt: 0x00000000 Cap:  3 Hit:  0 Rate:  60.84% code:     0 msg: 
%shell% \ShellCursor{}
%\end{Verbatim}
%
%<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">\textellipsis{}</span><span class="item info">compiledRegexCache.d</span></span></div><span class="shellOutput">
%  110: (\textbackslash{}[\{2\})(.+?)(]\{2\})  Opt: 0x0 Cap:  3 Hit:  0 Rate:  63.64% code:     0 msg: 
%  111: (\textbackslash{}[\{2\})(.+?)(]\{2\})  Opt: 0x0 Cap:  3 Hit:  1 Rate:  63.96% code:     0 msg: 
\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{sudo dtrace -Z -q -s compiledRegexCache.d}\ReturnKey{}
 131: (\textbackslash{}w+   Opt: 0x0 Cap: -1 Hit: -1 Rate:  63.36% code: 66310 msg: U\_REGEX\_MISMATCHED\textellipsis{}
 164: \textbackslash{}b\textbackslash{}s*  Opt: 0x0 Cap:  0 Hit:  0 Rate:  60.98% code:     0 msg: 
shell% \ShellCursor{}
\end{Verbatim}


An example that prints the number of times that a compiled regular expression was not in the cache per second:

\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{sudo dtrace -Z -q \textbackslash{}}
\Bd{-n 'RegexKitLite*:::compiledRegexCache /arg4==0/ \{ @miss[pid, execname] = count(); \}' \textbackslash{}}
\Bd{-n 'tick-1sec \{ printa("%-8d %-40s %@d/sec\textbackslash{}n", @miss); trunc(@miss); \}'}\ReturnKey{}
67003    RegexKitLite_tests                       16/sec
67008    RegexKitLite_tests                       50/sec
\Bd{\textasciicircum{}C}

shell% \ShellCursor{}
\end{Verbatim}

\pagebreak
\begin{RKLSeeAlso}
  \item \RKLCodePageRef{DTrace_RegexKitLiteProbePoints__compiledRegexCache}{RegexKitLite:::compiledRegexCache}
  \item \RKLSectionHref{http://docs.sun.com/app/docs/doc/817-6223}{Solaris Dynamic Tracing Guide} \RKLSectionHref{http://dlc.sun.com/pdf/817-6223/817-6223.pdf}{(as .PDF)}
\end{RKLSeeAlso}

The following is available in \File{examples/utf16ConversionCache.d} and demonstrates the use of all the arguments available via the \Code{RegexKitLite:::utf16ConversionCache} probe point.

%<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">utf16ConversionCache.d</span></span></div>
%\begin{lstlisting}
\begin{verbatim}
#!/usr/sbin/dtrace -s

enum {
  RKLCacheHitLookupFlag           = 1 << 0,
  RKLConversionRequiredLookupFlag = 1 << 1,
  RKLSetTextLookupFlag            = 1 << 2,
  RKLDynamicBufferLookupFlag      = 1 << 3,
  RKLErrorLookupFlag              = 1 << 4
};

RegexKitLite*:::utf16ConversionCache {
  this->eventID           = (unsigned long)arg0;
  this->lookupResultFlags = (unsigned int)arg1;
  this->hitRate           = (double *)copyin(arg2, sizeof(double));
  this->stringPtr         = (void *)arg3;
  this->NSRange_location  = (unsigned long)arg4;
  this->NSRange_length    = (unsigned long)arg5;
  this->length            = (long)arg6;

  printf("%5lu: flags: %#8.8x {Hit: %d Conv: %d SetText: %d Dyn: %d Error: %d}↩
        ↪ rate: %6.2f%% string: %#8.8p NSRange {%6lu, %6lu} length: %ld\n",
         this->eventID,
         this->lookupResultFlags,
         (this->lookupResultFlags & RKLCacheHitLookupFlag)           != 0,
         (this->lookupResultFlags & RKLConversionRequiredLookupFlag) != 0,
         (this->lookupResultFlags & RKLSetTextLookupFlag)            != 0,
         (this->lookupResultFlags & RKLDynamicBufferLookupFlag)      != 0,
         (this->lookupResultFlags & RKLErrorLookupFlag)              != 0,
         *this->hitRate,
         this->stringPtr,
         this->NSRange_location,
         this->NSRange_length,
         this->length);
}
\end{verbatim}

Below is an example of the output from \File{utf16ConversionCache.d}:

\RKLBoxNote{The output below has been significantly trimmed and altered to fit on a printed page.}
\vskip-\parskip\vskip-1em
%<div class="box shell"><div class="metainfo noPrintBorder"><span class="entry continues above"><span class="item meta">\textellipsis{}</span><span class="item info">utf16ConversionCache.d</span></span></div><span class="shellOutput">
%\begin{Verbatim}[commandchars=\\\{\}]
%shell% \Bd{sudo dtrace -Z -q -s utf16ConversionCache.d}\ReturnKey{}
%   85: flags: 0x00000000 \{Hit: 0 Conv: 0 SetText: 0 Dyn: 0 Error: 0\} rate:  59.18% string: 0x0010f530 NSRange \{     0,     18\} length: 18
%   86: flags: 0x00000004 \{Hit: 0 Conv: 0 SetText: 1 Dyn: 0 Error: 0\} rate:  59.18% string: 0x0010f530 NSRange \{     0,     18\} length: 18
%   87: flags: 0x00000006 \{Hit: 0 Conv: 1 SetText: 1 Dyn: 0 Error: 0\} rate:  58.00% string: 0x00054930 NSRange \{     1,     37\} length: 39
%   88: flags: 0x00000003 \{Hit: 1 Conv: 1 SetText: 0 Dyn: 0 Error: 0\} rate:  58.82% string: 0x00054930 NSRange \{     1,     37\} length: 39
%  109: flags: 0x00000006 \{Hit: 0 Conv: 1 SetText: 1 Dyn: 0 Error: 0\} rate:  53.62% string: 0x00054d00 NSRange \{     0,     56\} length: 56
%  110: flags: 0x00000006 \{Hit: 0 Conv: 1 SetText: 1 Dyn: 0 Error: 0\} rate:  52.86% string: 0x00054680 NSRange \{     0,   1064\} length: 1064
%  111: flags: 0x00000007 \{Hit: 1 Conv: 1 SetText: 1 Dyn: 0 Error: 0\} rate:  53.52% string: 0x00054680 NSRange \{    46,    978\} length: 1064
%shell% \ShellCursor{}
%\end{Verbatim}
%
\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{sudo dtrace -Z -q -s utf16ConversionCache.d}\ReturnKey{}
   85: flags: 0x0 \{Hit: 0 Conv: 0 Set: 0 Dyn: 0 Err: 0\} rate: 59.18% R \{ 0, 18\} L: 18
   86: flags: 0x4 \{Hit: 0 Conv: 0 Set: 1 Dyn: 0 Err: 0\} rate: 59.18% R \{ 0, 18\} L: 18
   87: flags: 0x6 \{Hit: 0 Conv: 1 Set: 1 Dyn: 0 Err: 0\} rate: 58.00% R \{ 1, 37\} L: 39
   88: flags: 0x3 \{Hit: 1 Conv: 1 Set: 0 Dyn: 0 Err: 0\} rate: 58.82% R \{ 1, 37\} L: 39
  109: flags: 0x6 \{Hit: 0 Conv: 1 Set: 1 Dyn: 0 Err: 0\} rate: 53.62% R \{ 0, 56\} L: 56
  110: flags: 0x6 \{Hit: 0 Conv: 1 Set: 1 Dyn: 0 Err: 0\} rate: 52.86% R \{ 0, 83\} L: 97
  111: flags: 0x7 \{Hit: 1 Conv: 1 Set: 1 Dyn: 0 Err: 0\} rate: 53.52% R \{46, 83\} L: 97
shell% \ShellCursor{}
\end{Verbatim}

An example that prints the number of times that a string required a conversion to \UTF{16} and was not in the cache per second:

\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{sudo dtrace -Z -q \textbackslash{}}
       \Bd{-n 'RegexKitLite*:::utf16ConversionCache /(arg1 & 0x3) == 0x2/ \textbackslash{}}
           \Bd{\{ @miss[pid, execname] = count(); \}' \textbackslash{}}
       \Bd{-n 'tick-1sec \{ printa("%-8d %-40s %@d/sec\textbackslash{}n", @miss); trunc(@miss); \}'}\ReturnKey{}
67020    RegexKitLite_tests                       73/sec
67037    RegexKitLite_tests                       64/sec
\Bd{\textasciicircum{}C}

shell% \ShellCursor{}
\end{Verbatim}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{DTrace_RegexKitLiteProbePoints__utf16ConversionCache}{RegexKitLite:::utf16ConversionCache}
  \item \RKLSectionPageRef{dtrace_utf16ConversionCache_lookupResultFlags}{RegexKitLite:::utf16ConversionCache arg1 Flags}
  \item \RKLSectionHref{http://docs.sun.com/app/docs/doc/817-6223}{Solaris Dynamic Tracing Guide} \RKLSectionHref{http://dlc.sun.com/pdf/817-6223/817-6223.pdf}{(as .PDF)}
\end{RKLSeeAlso}


\labeledchapter{ICUSyntax}{ICU Syntax}

In this section:

\begin{RKLBulletList}
  \item \RKLSectionPageRef{ICUSyntax_ICURegularExpressionSyntax}{ICU Regular Expression Syntax}
  \item \RKLSectionPageRef{ICUSyntax_ICURegularExpressionCharacterClasses}{ICU Regular Expression Character Classes}
  \item \RKLSectionPageRef{ICUSyntax_UnicodeProperties}{Unicode Properties}
  \item \RKLSectionPageRef{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax}
\end{RKLBulletList}

\labeledsection{ICUSyntax_ICURegularExpressionSyntax}{ICU Regular Expression Syntax}

For your convenience, the regular expression syntax from the ICU documentation is included below.  When in doubt, you should refer to the official \RKLSectionHref{http://userguide.icu-project.org/strings/regexp}{ICU User Guide - Regular Expressions} documentation page.

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://userguide.icu-project.org/strings/regexp}{ICU User Guide - Regular Expressions}
  \item \RKLSectionHref{http://www.unicode.org/reports/tr18/}{Unicode Technical Standard \#18 - Unicode Regular Expressions}
\end{RKLSeeAlso}

\begin{tabularx}{\textwidth}{|l|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Character} & \Bd{Description}\\\hline
\Regex{\textbackslash{}a} & Match a \UnicodeCharName{BELL}, \ConsoleText{\textbackslash{}u0007}\\\hline
\Regex{\textbackslash{}A} & Match at the beginning of the input. Differs from \Regex{\textasciicircum{}} in that \Regex{\textbackslash{}A} will not match after a \RegexDef{new-line} within the input.\\\hline
\Regex{\textbackslash{}b}, outside of a \Regex{[}\It{Set}\Regex{]} & 
Match if the current position is a word boundary. Boundaries occur at the transitions between \RegexDef{word} \Regex{\textbackslash{}w} and \RegexDef{non-word} \Regex{\textbackslash{}W} characters, with combining marks ignored. \newline \Bd{See also:} \RKLCodePageRef{RKLUnicodeWordBoundaries}{RKLUnicodeWordBoundaries}\\\hline
\Regex{\textbackslash{}b}, within a \Regex{[}\It{Set}\Regex{]} & Match a \UnicodeCharName{BACKSPACE}, \ConsoleText{\textbackslash{}u0008}.\\\hline
\Regex{\textbackslash{}B} & Match if the current position is not a \RegexDef{word} boundary.\\\hline
\Regex{\textbackslash{}c}\It{x} & Match a \HardNobr{\It{Control-x}} character.\\\hline
\Regex{\textbackslash{}d} & Match any character with the \It{Unicode General Category} of \Regex{\textbackslash{}p\{Nd\}} (\It{Number}, \It{Decimal Digit}).\\\hline
\Regex{\textbackslash{}D} & Match any character that is not a \RegexDef{decimal digit}.\\\hline
\Regex{\textbackslash{}e} & Match an \UnicodeCharName{ESCAPE}, \ConsoleText{\textbackslash{}u001B}.\\\hline
\Regex{\textbackslash{}E} & Terminates a \Regex{\textbackslash{}Q}\textellipsis{}\Regex{\textbackslash{}E} quoted sequence.\\\hline
\Regex{\textbackslash{}f} & Match a \UnicodeCharName{FORM FEED}, \ConsoleText{\textbackslash{}u000C}.\\\hline
\Regex{\textbackslash{}G} & Match if the current position is at the end of the previous match.\\\hline
\Regex{\textbackslash{}n} & Match a \UnicodeCharName{LINE FEED}, \ConsoleText{\textbackslash{}u000A}.\\\hline
\end{tabularx}

\begin{tabularx}{\textwidth}{|l|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Character} & \Bd{Description}\\\hline
\Regex{\textbackslash{}N\{}\It{Unicode Character Name}\Regex{\}} & Match the named \It{Unicode Character}.\\\hline
\Regex{\textbackslash{}p\{}\It{Unicode Property Name}\Regex{\}} & Match any character with the specified \It{Unicode Property}.\\\hline
\Regex{\textbackslash{}P\{}\It{Unicode Property Name}\Regex{\}} & Match any character not having the specified \It{Unicode Property}.\\\hline
\Regex{\textbackslash{}Q} & Quotes all following characters until \Regex{\textbackslash{}E}.\\\hline
\Regex{\textbackslash{}r} & Match a \UnicodeCharName{CARRIAGE RETURN}, \ConsoleText{\textbackslash{}u000D}.\\\hline
\label{ICUSyntax_ICURegularExpressionSyntax_white_space}\Regex{\textbackslash{}s} & {\RaggedRight Match a \RegexDef{white space} character. White space is defined as \Regex{[\textbackslash{}t\textbackslash{}n\textbackslash{}f\textbackslash{}r\textbackslash{}p\{Z\}]}.}\\\hline
\Regex{\textbackslash{}S} &  Match a non-\RegexDef{white space} character.\\\hline
\Regex{\textbackslash{}t} & Match a \UnicodeCharName{HORIZONTAL TABULATION}, \ConsoleText{\textbackslash{}u0009}.\\\hline
\Regex{\textbackslash{}u}\It{hhhh} & Match the character with the hex value \It{hhhh}.\\\hline
\Regex{\textbackslash{}U}\It{hhhhhhhh} & Match the character with the hex value \It{hhhhhhhh}. Exactly eight hex digits must be provided, even though the largest Unicode code point is \ConsoleText{\textbackslash{}U0010ffff}.\\\hline
\Regex{\textbackslash{}w} & {\RaggedRight Match a word character. Word characters are \Regex{[\textbackslash{}p\{Ll\}\textbackslash{}p\{Lu\}\textbackslash{}p\{Lt\}\textbackslash{}p\{Lo\}\textbackslash{}p\{Nd\}]}.}\\\hline
\Regex{\textbackslash{}W} & Match a non-word character.\\\hline
\Regex{\textbackslash{}x\{}\It{h}\textellipsis{}\Regex{\}} & Match the character with hex value \It{hhhh}. From one to six hex digits may be supplied.\\\hline
\Regex{\textbackslash{}x}\It{hh} & Match the character with two digit hex value \It{hh}.\\\hline
\Regex{\textbackslash{}X} & Match a \RKLSectionHref{http://www.unicode.org/reports/tr29/\#Grapheme\_Cluster\_Boundaries}{Grapheme Cluster}.\\\hline
\Regex{\textbackslash{}Z} & Match if the current position is at the end of input, but before the final line terminator, if one exists.\\\hline
\Regex{\textbackslash{}z} & Match if the current position is at the end of input.\\\hline
\Regex{\textbackslash{}}\It{n} & Back Reference. Match whatever the \It{n}th capturing group matched. \It{n} must be a number \textgreatereq{} 1 and \textlesseq{} total number of capture groups in the pattern.\\\hline
\Regex{[}\It{pattern}\Regex{]} & Match any one character from the set. See \RKLSectionPageRef{ICUSyntax_ICURegularExpressionCharacterClasses}{ICU Regular Expression Character Classes} for a full description of what may appear in the pattern.\\\hline
\Regex{.} & Match any character.\\\hline
\Regex{\textasciicircum{}} & Match at the beginning of a line.\\\hline
\Regex{\$} & Match at the end of a line.\\\hline
\Regex{\textbackslash{}} & Quotes the following character. Characters that must be quoted to be treated as literals are \ConsoleText{* ? + [ ( ) \{ \} \textasciicircum{} \$ | \textbackslash{} . /}\\\hline
\end{tabularx}


\begin{tabularx}{\textwidth}{|l|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Operator} & \Bd{Description}\\\hline
\Regex{|} & Alternation. \Regex{A|B} matches either \Regex{A} or \Regex{B}.\\\hline
\Regex{*} & Match zero or more times. Match as many times as possible.\\\hline
\Regex{+} & Match one or more times. Match as many times as possible.\\\hline
\Regex{?} & Match zero or one times. Prefer one.\\\hline
\Regex{\{}\It{n}\Regex{\}} & Match exactly \It{n} times.\\\hline
\Regex{\{}\It{n}\Regex{,\}} & Match at least \It{n} times. Match as many times as possible.\\\hline
\Regex{\{}\It{n}\Regex{,}\It{m}\Regex{\}} & Match between \It{n} and \It{m} times. Match as many times as possible, but not more than \It{m}.\\\hline
\Regex{*?} & Match zero or more times. Match as few times as possible.\\\hline
\Regex{+?} & Match one or more times. Match as few times as possible.\\\hline
\Regex{??} & Match zero or one times. Prefer zero.\\\hline
\Regex{\{}\It{n}\Regex{\}?} & Match exactly \It{n} times.\\\hline
\Regex{\{}\It{n}\Regex{,\}?} & Match at least \It{n} times, but no more than required for an overall pattern match.\\\hline
\Regex{\{}\It{n}\Regex{,}\It{m}\Regex{\}?} & Match between \It{n} and \It{m} times. Match as few times as possible, but not less than \It{n}.\\\hline
\Regex{*+} & Match zero or more times. Match as many times as possible when first encountered, do not retry with fewer even if overall match fails. Possessive match.\\\hline
\Regex{++} & Match one or more times. Possessive match.\\\hline
\Regex{?+} & Match zero or one times. Possessive match.\\\hline
\Regex{\{}\It{n}\Regex{\}+} & Match exactly \It{n} times. Possessive match.\\\hline
\Regex{\{}\It{n}\Regex{,\}+} & Match at least \It{n} times. Possessive match.\\\hline
\Regex{\{}\It{n}\Regex{,}\It{m}\Regex{\}+} & Match between \It{n} and \It{m} times. Possessive match.\\\hline
\Regex{(}\textellipsis{}\Regex{)} & Capturing parentheses. Range of input that matched the parenthesized subexpression is available after the match.\\\hline
\Regex{(?:}\textellipsis{}\Regex{)} & Non-capturing parentheses. Groups the included pattern, but does not provide capturing of matching text. Somewhat more efficient than capturing parentheses.\\\hline
\Regex{(?>}\textellipsis{}\Regex{)} & Atomic-match parentheses. First match of the parenthesized subexpression is the only one tried; if it does not lead to an overall pattern match, back up the search for a match to a position before the \Regex{(?>} .\\\hline
\Regex{(?\#}\textellipsis{}\Regex{)} & Free-format comment \Regex{(?\#}\It{comment}\Regex{)}.\\\hline
\Regex{(?=}\textellipsis{}\Regex{)} & Look-ahead assertion. True if the parenthesized pattern matches at the current input position, but does not advance the input position.\\\hline
\Regex{(?!}\textellipsis{}\Regex{)} & Negative look-ahead assertion. True if the parenthesized pattern does not match at the current input position. Does not advance the input position.\\\hline
\Regex{(?<=}\textellipsis{}\Regex{)} & Look-behind assertion. True if the parenthesized pattern matches text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no \Regex{*} or \Regex{+} operators).\\\hline
\Regex{(?<!}\textellipsis{}\Regex{)} & Negative Look-behind assertion. True if the parenthesized pattern does not match text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no \Regex{*} or \Regex{+} operators).\\\hline
\end{tabularx}

\begin{tabularx}{\textwidth}{|l|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Operator} & \Bd{Description}\\\hline
\Regex{(?ismwx-ismwx:}\textellipsis{}\Regex{)} & Flag settings. Evaluate the parenthesized expression with the specified flags \It{enabled} or \Regex{-}\It{disabled}.\\\hline
\Regex{(?ismwx-ismwx)} & Flag settings. Change the flag settings. Changes apply to the portion of the pattern following the setting. For example, \Regex{(?i)} changes to a case insensitive match. \newline \Bd{See also:} \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}\\\hline
\end{tabularx}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://userguide.icu-project.org/strings/regexp}{ICU User Guide - Regular Expressions}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}

\labeledsection{ICUSyntax_ICURegularExpressionCharacterClasses}{ICU Regular Expression Character Classes}

The following was originally from \RKLSectionHref{http://userguide.icu-project.org/strings/unicodeset}{ICU User Guide - UnicodeSet}, but has been adapted to fit the needs of this documentation.  Specifically, the ICU \Code{UnicodeSet} documentation describes an ICU C++ object\textendash{} \HardNobr{\Code{UnicodeSet}}.  The term \Code{UnicodeSet} was effectively replaced with \Bd{Character Class}, which is more appropriate in the context of regular expressions.  As always, you should refer to the original, official documentation when in doubt.

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://userguide.icu-project.org/strings/unicodeset}{ICU User Guide - UnicodeSet}
  \item \RKLSectionHref{http://www.unicode.org/reports/tr18/\#Subtraction\_and\_Intersection}{UTS \#18 Unicode Regular Expressions - Subtraction and Intersection}
  \item \RKLSectionHref{http://www.unicode.org/reports/tr18/\#Categories}{UTS \#18 Unicode Regular Expressions - Properties}
\end{RKLSeeAlso}

\subsection{Overview}

A character class is a regular expression pattern that represents a set of Unicode characters or character strings. The following table contains some example character class patterns:

\begin{tabular}{|l|l|}\hline
\rowcolor[gray]{0.8862745} \Bd{Pattern} & \Bd{Description}\\\hline
\Regex{[a-z]} & The lower case letters \Regex{a} through \Regex{z}\\\hline
\Regex{[abc123]} & The six characters \Regex{a}, \Regex{b}, \Regex{c}, \Regex{1}, \Regex{2}, and \Regex{3}\\\hline
\Regex{[\textbackslash{}p\{Letter\}]} & All characters with the Unicode \UnicodeProperty{General Category} of \UnicodeProperty{Letter}.\\\hline
\end{tabular}

\subsubsection{String Values}

In addition to being a set of Unicode code point characters, a character class may also contain string values. Conceptually, a character class is always a set of strings, not a set of characters.  Historically, regular expressions have treated \Regex{[}\textellipsis\Regex{]} character classes as being composed of single characters only, which is equivalent to a string that contains only a single character.

\subsection{Character Class Patterns}

Patterns are a series of characters bounded by square brackets that contain lists of characters and Unicode property sets. Lists are a sequence of characters that may have ranges indicated by a \Regex{-} between two characters, as in \HardNobr{\Regex{a-z}}. The sequence specifies the range of all characters from the left to the right, in Unicode order. For example, \HardNobr{\Regex{[a\textvisiblespace{}c\textvisiblespace{}d-f\textvisiblespace{}m]}} is equivalent to \HardNobr{\Regex{[a\textvisiblespace{}c\textvisiblespace{}d\textvisiblespace{}e\textvisiblespace{}f\textvisiblespace{}m]}}. Whitespace can be freely used for clarity as \HardNobr{\Regex{[a\textvisiblespace{}c\textvisiblespace{}d-f\textvisiblespace{}m]}} means the same as \HardNobr{\Regex{[acd-fm]}}.
  
Unicode property sets are specified by a Unicode property, such as \Regex{[:Letter:]}. ICU version 2.0 supports \UnicodeProperty{General Category}, \UnicodeProperty{Script}, and \UnicodeProperty{Numeric Value} properties (ICU will support additional properties in the future). For a list of the property names, see the end of this section. The syntax for specifying the property names is an extension of either POSIX or Perl syntax with the addition of \Regex{=value}. For example, you can match letters by using the POSIX syntax \Regex{[:Letter:]}, or by using the Perl syntax \Regex{\textbackslash{}p\{Letter\}}. The type can be omitted for the \UnicodeProperty{Category} and \UnicodeProperty{Script} properties, but is required for other properties.

The following table lists the standard and negated forms for specifying Unicode properties in both POSIX or Perl syntax. The negated form specifies a character class that includes everything but the specified property. For example, \Regex{[:\textasciicircum{}Letter:]} matches all characters that are not \Regex{[:Letter:]}.

\begin{tabular}{|l|l|l|}\hline
\rowcolor[gray]{0.8862745} \Bd{Syntax Style} & \Bd{Standard} & \Bd{Negated}\\\hline
POSIX & \Regex{[:}\It{type=value}\Regex{:]} & \Regex{[:\textasciicircum{}}\It{type=value}\Regex{:]}\\\hline
Perl & \Regex{\textbackslash{}p\{}\It{type=value}\Regex{\}} & \Regex{\textbackslash{}P\{}\It{type=value}\Regex{\}}\\\hline
\end{tabular}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://www.unicode.org/reports/tr18/\#Categories}{UTS \#18 Unicode Regular Expressions - Properties}
\end{RKLSeeAlso}

Character classes can then be modified using standard set operations\textellipsis{} Union, Inverse, Difference, and Intersection.

\begin{RKLBulletList}
  \item To union two sets, simply concatenate them. For example, \Regex{[[:letter:]~[:number:]]}
  \item To intersect two sets, use the \Regex{\&} operator. For example, \Regex{[[:letter:]~\&~[a-z]]}
  \item To take the set-difference of two sets, use the \Regex{-} operator. For example, \Regex{[[:letter:]~-~[a-z]]}
  \item To invert a set, place a \Regex{\textasciicircum{}} immediately after the opening \Regex{[}. For example, \Regex{[\textasciicircum{}a-z]}. In any other location, the \Regex{\textasciicircum{}} does not have a special meaning.
\end{RKLBulletList}\vspace{-\parskip}\vspace{-\parskip}

The binary operators \Regex{\&} and \Regex{-} have equal precedence and bind left-to-right. Thus \linebreak \Regex{[[:letter:]-[a-z]-[\textbackslash{}u0100-\textbackslash{}u01FF]]} is equivalent to \Regex{[[[:letter:]-[a-z]]-[\textbackslash{}u0100-\textbackslash{}u01FF]]}. \linebreak Another example is the set \Regex{[[ace][bdf]~-~[abc][def]]} is \Bd{not} the empty set, but instead the set \Regex{[def]}. This only really matters for the difference operation, as the intersection operation is commutative.
  
Another caveat with the \Regex{\&} and \Regex{-} operators is that they operate between \Bd{sets}. That is, they must be immediately preceded and immediately followed by a set. For example, the pattern \Regex{[[:Lu:]-A]} is illegal, since it is interpreted as the set \Regex{[:Lu:]} followed by the incomplete range \Regex{-A}. To specify the set of uppercase letters except for \Regex{A}, enclose the \Regex{A} in a set: \Regex{[[:Lu:]-[A]]}.

\begin{tabularx}{\textwidth}{|l|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Pattern} & \Bd{Description}  \\\hline
\Regex{[a]} & The set containing \Regex{a}.  \\\hline
\Regex{[a-z]} & The set containing \Regex{a} through \Regex{z} and all letters in between, in Unicode order.  \\\hline
\Regex{[\textasciicircum{}a-z]} & The set containing all characters but \Regex{a} through \Regex{z}, that is, \Code{U+0000} through \Code{a-1} and \Code{z+1} through \Code{U+FFFF}.  \\\hline
\Regex{[[}\It{pat1}\Regex{][}\It{pat2}\Regex{]]} & The union of sets specified by \It{pat1} and \It{pat2}.  \\\hline
\Regex{[[}\It{pat1}\Regex{]\&[}\It{pat2}\Regex{]]} & The intersection of sets specified by \It{pat1} and \It{pat2}.  \\\hline
\Regex{[[}\It{pat1}\Regex{]-[}\It{pat2}\Regex{]]} & The asymmetric difference of sets specified by \It{pat1} and \It{pat2}.  \\\hline
\Regex{[:Lu:]} & The set of characters belonging to the given Unicode category.  In this case, Unicode uppercase letters. The long form for this is \Regex{[:UppercaseLetter:]}.  \\\hline
\Regex{[:L:]} & The set of characters belonging to all Unicode categories starting with \UnicodeProperty{L}, that is, \Regex{[[:Lu:][:Ll:][:Lt:][:Lm:][:Lo:]]}. The long form for this is \Regex{[:Letter:]}.  \\\hline
\end{tabularx}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://www.unicode.org/reports/tr18/\#Subtraction\_and\_Intersection}{UTS \#18 Unicode Regular Expressions - Subtraction and Intersection}
\end{RKLSeeAlso}

\subsubsection{String Values in Character Classes}

String values are enclosed in \Regex{\{}\It{curly brackets}\Regex{\}}.  For example:

\begin{tabularx}{\textwidth}{|l|X|}\hline
\rowcolor[gray]{0.8862745}\Bd{Pattern} & \Bd{Description}\\\hline
\Regex{[abc\{def\}]} & A set containing four members, the single characters \Regex{a}, \Regex{b}, and \Regex{c} and the string \Regex{def}.\\\hline
\Regex{[\{abc\}\{def\}]} & A set containing two members, the string \Regex{abc} and the string \Regex{def}.\\\hline
\Regex{[\{a\}\{b\}\{c\}][abc]} & These two sets are equivalent. Each contains three items, the three individual characters \Regex{a}, \Regex{b}, and \Regex{c}. A \Regex{\{}\It{string}\Regex{\}} containing a single character is equivalent to that same character specified in any other way. \\\hline
\end{tabularx}

\subsection{Character Quoting and Escaping in ICU Character Class Patterns}

\subsubsection{Single Quote}

Two single quotes represent a single quote, either inside or outside single quotes. Text within single quotes is not interpreted in any way, except for two adjacent single quotes. It is taken as literal text\textendash{}~ special characters become non-special. These quoting conventions for ICU character classes differ 

\subsubsection{Backslash Escapes}

Outside of single quotes, certain backslashed characters have special meaning:

\begin{tabular}{|l|l|}\hline
\rowcolor[gray]{0.8862745} \Bd{Pattern} & \Bd{Description}\\\hline
\Regex{\textbackslash{}u}\It{hhhh} & Exactly 4 hex digits; \It{h} in \Regex{[0-9A-Fa-f]}\\\hline
\Regex{\textbackslash{}U}\It{hhhhhhhh} & Exactly 8 hex digits\\\hline
\Regex{\textbackslash{}x}\It{hh} & 1-2 hex digits\\\hline
\Regex{\textbackslash{}}\It{ooo} & 1-3 octal digits; \It{o} in \Regex{[0-7]}\\\hline
\Regex{\textbackslash{}a} & \Code{U+0007} \UnicodeCharName{BELL}\\\hline
\Regex{\textbackslash{}b} & \Code{U+0008} \UnicodeCharName{BACKSPACE}\\\hline
\Regex{\textbackslash{}t} & \Code{U+0009} \UnicodeCharName{HORIZONTAL TAB}\\\hline
\Regex{\textbackslash{}n} & \Code{U+000A} \UnicodeCharName{LINE FEED}\\\hline
\Regex{\textbackslash{}v} & \Code{U+000B} \UnicodeCharName{VERTICAL TAB}\\\hline
\Regex{\textbackslash{}f} & \Code{U+000C} \UnicodeCharName{FORM FEED}\\\hline
\Regex{\textbackslash{}r} & \Code{U+000D} \UnicodeCharName{CARRIAGE RETURN}\\\hline
\Regex{\textbackslash{}\textbackslash{}} & \Code{U+005C} \UnicodeCharName{BACKSLASH}\\\hline
\end{tabular}
  
Anything else following a backslash is mapped to itself, except in an environment where it is defined to have some special meaning. For example, \Regex{\textbackslash{}p\{Lu\}} is the set of uppercase letters. Any character formed as the result of a backslash escape loses any special meaning and is treated as a literal. In particular, note that \Regex{\textbackslash{}u} and \Regex{\textbackslash{}U} escapes create literal characters.

\subsubsection{Whitespace}

Whitespace, as defined by the ICU API, is ignored unless it is quoted or backslashed.
\pagebreak[0]

\subsection{Property Values}

The following property value styles are recognized:

\begin{tabularx}{\textwidth}{|l|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Style} & \Bd{Description}\\\hline
Short & Omits the \Regex{=type} argument. Used to prevent ambiguity and only allowed with the \UnicodeProperty{Category} and \UnicodeProperty{Script} properties.\\\hline
Medium & Uses an abbreviated \Regex{type} and \Regex{value}.\\\hline
Long & Uses a full \Regex{type} and \Regex{value}.\\\hline
\end{tabularx}
  
If the \Regex{type} or \Regex{value} is omitted, then the \Regex{=} equals sign is also omitted. The short style is only used for \UnicodeProperty{Category} and \UnicodeProperty{Script} properties because these properties are very common and their omission is unambiguous.

In actual practice, you can mix \Regex{type} names and \Regex{values} that are omitted, abbreviated, or full. For example, if \UnicodeProperty{Category=Unassigned} you could use what is in the table explicitly, \Regex{\textbackslash{}p\{gc=Unassigned\}}, \Regex{\textbackslash{}p\{Category=Cn\}}, or \Regex{\textbackslash{}p\{Unassigned\}}.

When these are processed, case and whitespace are ignored so you may use them for clarity, if desired. For example, \Regex{\textbackslash{}p\{Category~=~Uppercase~Letter\}} or \Regex{\textbackslash{}p\{Category~=~uppercase~letter\}}.

For a list of properties supported by ICU, see \RKLSectionHref{http://userguide.icu-project.org/strings/properties}{ICU User Guide - Unicode Properties}.

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://userguide.icu-project.org/strings/properties}{ICU User Guide - Unicode Properties}
  \item \RKLSectionHref{http://www.unicode.org/reports/tr18/\#Categories}{UTS \#18 Unicode Regular Expressions - Properties}
\end{RKLSeeAlso}

\labeledsection{ICUSyntax_UnicodeProperties}{Unicode Properties}

The following tables list some of the commonly used Unicode Properties, which can be matched in a regular expression with \Regex{\textbackslash{}p\{}\It{Property}\Regex{\}}. The tables were created from the \RKLHref{http://www.unicode.org/versions/Unicode5.2.0/}{Unicode 5.2} Unicode Character Database, which is the version used by ICU that ships with \MacOSX{ 10.6}.

\begin{tabular}[t]{lll}
\begin{tabular}[t]{|l|l|}\hline
\multicolumn{2}{|c|}{\cellcolor[gray]{0.8862745} \Bd{Category}}\\\hline
\ConsoleText{N} & \ConsoleText{Number}\\\hline
\ConsoleText{Nd} & \ConsoleText{DecimalNumber}\\\hline
\ConsoleText{Nl} & \ConsoleText{LetterNumber}\\\hline
\ConsoleText{No} & \ConsoleText{OtherNumber}\\\hline
\multicolumn{2}{c}{}\\\hline
\ConsoleText{L} & \ConsoleText{Letter}\\\hline
\ConsoleText{LC} & \ConsoleText{CasedLetter}\\\hline
\ConsoleText{Lu} & \ConsoleText{UppercaseLetter}\\\hline
\ConsoleText{Ll} & \ConsoleText{LowercaseLetter}\\\hline
\ConsoleText{Lt} & \ConsoleText{TitlecaseLetter}\\\hline
\ConsoleText{Lm} & \ConsoleText{ModifierLetter}\\\hline
\ConsoleText{Lo} & \ConsoleText{OtherLetter}\\\hline
\end{tabular} & %
%
\begin{tabular}[t]{|l|l|}\hline
\multicolumn{2}{|c|}{\cellcolor[gray]{0.8862745} \Bd{Category}}\\\hline
\ConsoleText{M} & \ConsoleText{Mark}\\\hline
\ConsoleText{Mn} & \ConsoleText{NonspacingMark}\\\hline
\ConsoleText{Mc} & \ConsoleText{SpacingMark}\\\hline
\ConsoleText{Me} & \ConsoleText{EnclosingMark}\\\hline
\multicolumn{2}{c}{}\\\hline
\ConsoleText{P} & \ConsoleText{Punctuation}\\\hline
\ConsoleText{Pc} & \ConsoleText{ConnectorPunctuation}\\\hline
\ConsoleText{Pd} & \ConsoleText{DashPunctuation}\\\hline
\ConsoleText{Ps} & \ConsoleText{OpenPunctuation}\\\hline
\ConsoleText{Pe} & \ConsoleText{ClosePunctuation}\\\hline
\ConsoleText{Pi} & \ConsoleText{InitialPunctuation}\\\hline
\ConsoleText{Pf} & \ConsoleText{FinalPunctuation}\\\hline
\ConsoleText{Po} & \ConsoleText{OtherPunctuation}\\\hline
\end{tabular} & %
%
\begin{tabular}[t]{|l|l|}\hline
\multicolumn{2}{|c|}{\cellcolor[gray]{0.8862745} \Bd{Category}}\\\hline
\ConsoleText{Z} & \ConsoleText{Separator}\\\hline
\ConsoleText{Zs} & \ConsoleText{SpaceSeparator}\\\hline
\ConsoleText{Zl} & \ConsoleText{LineSeparator}\\\hline
\ConsoleText{Zp} & \ConsoleText{ParagraphSeparator}\\\hline
\multicolumn{2}{c}{}\\\hline
\ConsoleText{C} & \ConsoleText{Other}\\\hline
\ConsoleText{Cc} & \ConsoleText{Control}\\\hline
\ConsoleText{Cf} & \ConsoleText{Format}\\\hline
\ConsoleText{Cs} & \ConsoleText{Surrogate}\\\hline
\ConsoleText{Co} & \ConsoleText{PrivateUse}\\\hline
\ConsoleText{Cn} & \ConsoleText{Unassigned}\\\hline
\end{tabular}%
\end{tabular}%


\begin{tabular}[t]{lr}
\begin{tabular}[t]{|l|l|}\hline
\multicolumn{2}{|c|}{\cellcolor[gray]{0.8862745} \Bd{Category}}\\\hline
\ConsoleText{S} & \ConsoleText{Symbol}\\\hline
\ConsoleText{Sm} & \ConsoleText{MathSymbol}\\\hline
\ConsoleText{Sc} & \ConsoleText{CurrencySymbol}\\\hline
\ConsoleText{Sk} & \ConsoleText{ModifierSymbol}\\\hline
\ConsoleText{So} & \ConsoleText{OtherSymbol}\\\hline
\end{tabular} & %
%
\begin{tabular}[t]{|l|l|}\hline
\multicolumn{2}{|c|}{\cellcolor[gray]{0.8862745} \Bd{Extended Property Class}}\\\hline
\ConsoleText{ASCII\_Hex\_Digit} & \ConsoleText{Alphabetic}\\\hline
\ConsoleText{Bidi\_Control} & \ConsoleText{Dash}\\\hline
\ConsoleText{Default\_Ignorable\_Code\_Point} & \ConsoleText{Deprecated}\\\hline
\ConsoleText{Diacritic} & \ConsoleText{Extender}\\\hline
\ConsoleText{Grapheme\_Base} & \ConsoleText{Grapheme\_Extend}\\\hline
\ConsoleText{Grapheme\_Link} & \ConsoleText{Hex\_Digit}\\\hline
\ConsoleText{Hyphen} & \ConsoleText{IDS\_Binary\_Operator}\\\hline
\ConsoleText{IDS\_Trinary\_Operator} & \ConsoleText{ID\_Continue}\\\hline
\ConsoleText{ID\_Start} & \ConsoleText{Ideographic}\\\hline
\ConsoleText{Join\_Control} & \ConsoleText{Logical\_Order\_Exception}\\\hline
\ConsoleText{Lowercase} & \ConsoleText{Math}\\\hline
\ConsoleText{Noncharacter\_Code\_Point} & \ConsoleText{Other\_Alphabetic}\\\hline
\ConsoleText{Other\_Default\_Ignorable\_Code\_Point} & \ConsoleText{Other\_Grapheme\_Extend}\\\hline
\ConsoleText{Other\_ID\_Continue} & \ConsoleText{Other\_ID\_Start}\\\hline
\ConsoleText{Other\_Lowercase} & \ConsoleText{Other\_Math}\\\hline
\ConsoleText{Other\_Uppercase} & \ConsoleText{Pattern\_Syntax}\\\hline
\ConsoleText{Pattern\_White\_Space} & \ConsoleText{Quotation\_Mark}\\\hline
\ConsoleText{Radical} & \ConsoleText{STerm}\\\hline
\ConsoleText{Soft\_Dotted} & \ConsoleText{Terminal\_Punctuation}\\\hline
\ConsoleText{Unified\_Ideograph} & \ConsoleText{Uppercase}\\\hline
\ConsoleText{Variation\_Selector} & \ConsoleText{White\_Space}\\\hline
\ConsoleText{XID\_Continue} & \ConsoleText{XID\_Start}\\\hline
\end{tabular}\\%
%
\multicolumn{2}{c}{%
\begin{tabular}[t]{|l|l|l|l|l|l|}\hline
\multicolumn{6}{|c|}{\cellcolor[gray]{0.8862745} \Bd{Script}}\\\hline
\ConsoleText{Arabic} & \ConsoleText{Armenian} & \ConsoleText{Balinese} & \ConsoleText{Bengali} & \ConsoleText{Bopomofo} & \ConsoleText{Braille}\\\hline
\ConsoleText{Buginese} & \ConsoleText{Buhid} & \ConsoleText{Canadian\_Aboriginal} & \ConsoleText{Carian} & \ConsoleText{Cham} & \ConsoleText{Cherokee}\\\hline
\ConsoleText{Common} & \ConsoleText{Coptic} & \ConsoleText{Cuneiform} & \ConsoleText{Cypriot} & \ConsoleText{Cyrillic} & \ConsoleText{Deseret}\\\hline
\ConsoleText{Devanagari} & \ConsoleText{Ethiopic} & \ConsoleText{Georgian} & \ConsoleText{Glagolitic} & \ConsoleText{Gothic} & \ConsoleText{Greek}\\\hline
\ConsoleText{Gujarati} & \ConsoleText{Gurmukhi} & \ConsoleText{Han} & \ConsoleText{Hangul} & \ConsoleText{Hanunoo} & \ConsoleText{Hebrew}\\\hline
\ConsoleText{Hiragana} & \ConsoleText{Inherited} & \ConsoleText{Kannada} & \ConsoleText{Katakana} & \ConsoleText{Kayah\_Li} & \ConsoleText{Kharoshthi}\\\hline
\ConsoleText{Khmer} & \ConsoleText{Lao} & \ConsoleText{Latin} & \ConsoleText{Lepcha} & \ConsoleText{Limbu} & \ConsoleText{Linear\_B}\\\hline
\ConsoleText{Lycian} & \ConsoleText{Lydian} & \ConsoleText{Malayalam} & \ConsoleText{Mongolian} & \ConsoleText{Myanmar} & \ConsoleText{New\_Tai\_Lue}\\\hline
\ConsoleText{Nko} & \ConsoleText{Ogham} & \ConsoleText{Ol\_Chiki} & \ConsoleText{Old\_Italic} & \ConsoleText{Old\_Persian} & \ConsoleText{Oriya}\\\hline
\ConsoleText{Osmanya} & \ConsoleText{Phags\_Pa} & \ConsoleText{Phoenician} & \ConsoleText{Rejang} & \ConsoleText{Runic} & \ConsoleText{Saurashtra}\\\hline
\ConsoleText{Shavian} & \ConsoleText{Sinhala} & \ConsoleText{Sundanese} & \ConsoleText{Syloti\_Nagri} & \ConsoleText{Syriac} & \ConsoleText{Tagalog}\\\hline
\ConsoleText{Tagbanwa} & \ConsoleText{Tai\_Le} & \ConsoleText{Tamil} & \ConsoleText{Telugu} & \ConsoleText{Thaana} & \ConsoleText{Thai}\\\hline
\ConsoleText{Tibetan} & \ConsoleText{Tifinagh} & \ConsoleText{Ugaritic} & \ConsoleText{Unknown} & \ConsoleText{Vai} & \ConsoleText{Yi}\\\hline
\end{tabular}%
}%
\end{tabular}


\subsubsection{Unicode Character Database}

Unicode properties are defined in the \RKLHref{http://www.unicode.org/ucd/}{Unicode Character Database}, or \Bd{UCD}. From time to time the UCD is \RKLHref{http://www.unicode.org/versions/}{revised and updated}. The properties available, and the definition of the characters they match, depend on the UCD that ICU was built with.

\RKLBoxNote{In general, the ICU and UCD versions change with each major operating system release.}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://www.unicode.org/reports/tr18/\#Categories}{UTS \#18 Unicode Regular Expressions - Properties}
  \item \RKLSectionHref{http://www.unicode.org/reports/tr18/\#Compatibility\_Properties}{UTS \#18 Unicode Regular Expressions - Compatibility Properties}
  \item \RKLSectionHref{http://www.unicode.org/ucd/}{Unicode Character Database}
  \item \RKLSectionHref{http://www.unicode.org/versions/Unicode5.2.0/}{The Unicode Standard - Unicode 5.2}
  \item \RKLSectionHref{http://www.unicode.org/versions/}{Versions of the Unicode Standard}
\end{RKLSeeAlso}

\labeledsection{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax}

\begin{tabularx}{\textwidth}{|l|X|}\hline
\rowcolor[gray]{0.8862745}Character & Description\\\hline
\Gape[2pt]{\makecell{\Regex{\$}\It{n}}} & \Gape[2pt][-14pt]{\makecell[c{X}]{The text of capture group \It{n} will be substituted for \Regex{\$}\It{n}. \It{n} must be \textgreatereq{} \ConsoleText{0} and not greater than the number of capture groups.  A \Regex{\$} not followed by a digit has no special meaning, and will appear in the substitution text as itself, a \Regex{\$}.%
%
\RKLBoxImportant{Methods will raise a \RKLCodePageRef{RKLICURegexException}{RKLICURegexException} if \It{n} is greater than the number of capture groups in the regular expression.}}}\\\hline
\Gape[2pt]{\makecell{\Regex{\textbackslash}}} & \Gape[2pt][-12pt]{\makecell[c{X}]{Treat the character following the backslash as a literal, suppressing any special meaning.  Backslash escaping in substitution text is only required for \Regex{\$} and \Regex{\textbackslash{}}, but may proceed any character.  The backslash itself will not be copied to the substitution text.}}\\\hline
\end{tabularx}%\vskip 4pt plus 2pt minus 2pt

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://userguide.icu-project.org/strings/regexp\#TOC-Replacement-Text}{ICU User Guide - Replacement Text}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:options:range:error:}{- replaceOccurrencesOfRegex:withString:options:range:error:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:options:range:error:}{- stringByReplacingOccurrencesOfRegex:withString:options:range:error:}

\end{RKLSeeAlso}

\labeledchapter{RegexKitLiteCookbook}{\protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} Cookbook}

\begin{quote}
  \textit{Some people, when confronted with a problem, think \textquotedblleft{}I know, I\textquoteright{}ll use regular expressions.\textquotedblright{}\linebreak{}Now they have two problems.}
\qattribute{Jamie Zawinski}
\end{quote}

This section contains a collection of regular expressions and example code demonstrating how \RegexKitLite{} makes some common programming choirs easier. \RegexKitLite{} makes it easy to match part of a string and extract just that part, or even create an entirely new string using just a few pieces of the original string.  A great example of this is a string that contains a URL and you need to extract just a part of it, perhaps the host or maybe just the port used.  This example demonstrates how easy it is to extract the port used from a URL, which is then converted in to a \Code{NSInteger} value:

\begin{lstlisting}
searchString = @"http://www.example.com:8080/index.html";
regexString  = @"\\bhttps?://[a-zA-Z0-9\\-.]+(?::(\\d+))?"
               @"(?:(?:/[a-zA-Z0-9\\-._?,'+\\&%$=~*!():@\\\\]*)+)?";

NSInteger portInteger = [[searchString stringByMatching:regexString
                                                capture:1L] integerValue];

NSLog(@"portInteger: '%ld'", (long)portInteger);
// 2008-10-15 08:52:52.500 host_port[8021:807] portInteger: '8080'
\end{lstlisting}

\section{Pattern Matching Recipes}

Inside you'll find more examples like this that you can use as the starting point for your own regular expression pattern matching solution. Keep in mind that these are meant to be examples to help get you started and not necessarily the ideal solution for every need. Trade-offs are usually made when creating a regular expression, matching an email address is a perfect example of this.  A regular expression that precisely matches the formal definition of email address is both complicated and usually unnecessary.  Knowing which trade-offs are acceptable requires that you understand what it is you're trying to match, the data that you're searching through, and the requirements and uses of the matched results. It won't take long until you gain an appreciation for Jamie Zawinski's infamous quote.

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://oreilly.com/catalog/9780596528126/}{O'Reilly - Mastering Regular Expressions, 3rd edition by Jeffrey Friedl}
  \item \RKLSectionHref{http://oreilly.com/catalog/9780596520694/}{O'Reilly - Regular Expressions Cookbook by Jan Goyvaerts and Steven Levithan}
  \item \RKLSectionHref{http://regexlib.com/}{RegExLib.com - Regular Expression Library}
  \item \RKLSectionHref{http://userguide.icu-project.org/strings/regexp}{ICU Userguide - Regular Expressions}
  \item \RKLSectionHref{http://www.regular-expressions.info/}{Regular-Expressions.info - Regex Tutorial, Examples, and Reference}
  \item \RKLSectionHref{http://en.wikipedia.org/wiki/Regular\_expression}{Wikipedia - Regular Expression}
\end{RKLSeeAlso}

\section{Numbers}

\begin{tabularx}{\textwidth}{|l|X|l|}\hline
\rowcolor[gray]{0.8862745} \Bd{Description} & \Bd{Regex} & \Bd{Examples} \\\hline
Integer & \Regex{[+\textbackslash{}-]?[0-9]+} & \ConsoleText{\underline{123}}\hspace{1.2ex}\ConsoleText{\underline{-42}}\hspace{1.2ex}\ConsoleText{\underline{+23}}\\\hline
Hex Number & \Regex{0[xX][0-9a-fA-F]+} & \ConsoleText{\underline{0x0}}\hspace{1.2ex}\ConsoleText{\underline{0xdeadbeef}}\hspace{1.2ex}\ConsoleText{\underline{0xF3}}\\\hline
Floating Point & \Regex{[+\textbackslash{}-]?(?:[0-9]*\textbackslash{}.[0-9]+|\RegexBreak{}[0-9]+\textbackslash{}.)} & \ConsoleText{\underline{123.}}\hspace{1.2ex}\ConsoleText{\underline{.123}}\hspace{1.2ex}\ConsoleText{\underline{+.42}}\\\hline
Floating Point with Exponent & \Regex{[+\textbackslash{}-]?(?:[0-9]*\textbackslash{}.[0-9]+|\RegexBreak{}[0-9]+\textbackslash{}.)(?:[eE][+\textbackslash{}-]?[0-9]+)?} & \ConsoleText{\underline{123.}}\hspace{1.2ex}\ConsoleText{\underline{.123}}\hspace{1.2ex}\ConsoleText{\underline{10.0E13}}\hspace{1.2ex}\ConsoleText{\underline{1.23e-7}}\\\hline
Comma Separated Number & \Regex{[0-9]\{1,3\}(?:,[0-9]\{3\})*} & \ConsoleText{\underline{42}}\hspace{1.2ex}\ConsoleText{\underline{1,234}}\hspace{1.2ex}\ConsoleText{\underline{1,234,567}}\\\hline
Comma Separated Number & \Regex{[0-9]\{1,3\}(?:,[0-9]\{3\})*\RegexBreak{}(?:\textbackslash{}.[0-9]+)?} & \ConsoleText{\underline{42}}\hspace{1.2ex}\ConsoleText{\underline{1,234}}\hspace{1.2ex}\ConsoleText{\underline{1,234,567.89}}\\\hline
\end{tabularx}
  
\subsection{Extracting and Converting Numbers}

\Code{NSString} includes several methods for converting the contents of the string in to a numeric value in the various C primitive types.  The following demonstrates the matching of an \Code{int} and \Code{double} in a \Code{NSString}, and then converting the matched string in to its base type.
  
%  <div class="box sourcecode clearBoth"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Integer conversion\textellipsis{}</span></span></div>
\begin{lstlisting}
NSString *searchString = @"The int 5542 to convert";
NSString *regexString  = @"([+\\-]?[0-9]+)";
int       matchedInt   = [[searchString stringByMatching:regexString 
                                                 capture:1L] intValue];
\end{lstlisting}

The variable \Code{matchedInt} now contains the value of \Code{5542}.

%  <div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Floating Point conversion\textellipsis{}</span></span></div>
\begin{lstlisting}
NSString *searchString  = @"The double 4321.9876 to convert";
NSString *regexString   = @"([+\\-]?(?:[0-9]*\\.[0-9]+|[0-9]+\\.))";
double    matchedDouble = [[searchString stringByMatching:regexString
                                                  capture:1L] doubleValue];
\end{lstlisting}

The variable \Code{matchedDouble} now contains the value of \Code{4321.9876}.~ \Code{doubleValue} can even convert numbers that are in scientific notation, which represent numbers as $n \times 10^{exp}$:

%<div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Floating Point conversion\textellipsis{}</span></span></div>
\begin{lstlisting}
NSString *searchString  = @"The double 1.010489e5 to convert";
NSString *regexString   = @"([+\\-]?(?:[0-9]*\\.[0-9]+|[0-9]+\\.)"
                          @"(?:[eE][+\\-]?[0-9]+)?)";
double    matchedDouble = [[searchString stringByMatching:regexString
                                                  capture:1L] doubleValue];
\end{lstlisting}

The variable \Code{matchedDouble} now contains the value of \Code{101048.9}.

\subsection{Extracting and Converting Hex Numbers}

Converting a string that contains a hex number in to a more basic type, such as an \Code{int}, takes a little more work.  Unfortunately, Foundation does not provide an easy way to convert a hex value in a string in to a more basic type as it does with \Code{intValue} or \Code{doubleValue}.  Thankfully the standard C library provides a set of functions for performing such a conversion.  For this example we will use the \Code{strtol()} (\It{string to long}) function to convert the hex value we've extracted from \Code{searchString}.  We can not pass the pointer to the \Code{NSString} object that contains the matched hex value since \Code{strtol()} is part of the standard C library which can only work on pointers to C strings.  We use the \Code{UTF8String} method to get a pointer to a compatible C string of the matched hex value.

%<div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Hex conversion\textellipsis{}</span></span></div>
\begin{lstlisting}
NSString *searchString = @"A hex value: 0x0badf00d";
NSString *regexString  = @"\\b(0[xX][0-9a-fA-F]+)\\b";

NSString *hexString    = [searchString stringByMatching:regexString capture:1L];

// Use strtol() to convert the string to a long.
long hexLong = strtol([hexString UTF8String], NULL, 16);

NSLog(@"hexLong: 0x%lx / %ld", (u_long)hexLong, hexLong);
// 2008-09-01 09:40:44.848 hex_example[30583:807] hexLong: 0xbadf00d / 195948557
\end{lstlisting}

The full set of \It{string to\textellipsis{}} functions are: \Code{strtol()}, \Code{strtoll()}, \Code{strtoul()}, and \Code{strtoull()}.  These convert a string value, from base 2 to base 36, in to a \Code{long}, \Code{long long}, \Code{unsigned long}, and \Code{unsigned long long} respectively.

\subsubsection{Adding Hex Value Conversions to \protect\texorpdfstring{\Code{NSString}}{NSString}}

Since it seems to be a frequently asked question, and a common search engine query for RegexKit web site visitors, here is a \Code{NSString} category addition that converts the receivers text in to a \Code{NSInteger} value.  This is the same functionality as \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html\#//apple\_ref/occ/instm/NSString/intValue}{intValue} or \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html\#//apple\_ref/occ/instm/NSString/doubleValue}{doubleValue}, except that it converts hexadecimal text values instead of decimal text values.

\RKLBoxNote{The following code can also be found in the \RegexKitLite{} distributions \File{examples/} directory.}

The example conversion code is fairly quick since it uses \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation} directly along with the stack to hold any temporary string conversions.  Any whitespace at the beginning of the string will be skipped and the hexadecimal text to be converted may be optionally prefixed with either \ConsoleText{0x} or \ConsoleText{0X}.  Returns \Code{0} if the receiver does not begin with a valid hexadecimal text representation. Refer to \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man3/strtol.3.html}{strtol(3)} for additional conversion details.

\RKLBoxImportant{If the receiver needs to be converted in to an encoding that is compatible with \Code{strtol()}, only the first sixty characters of the receiver are converted.}

%<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">NSString-HexConversion.h</span></span></div>
\begin{lstlisting}
#import <Foundation/NSString.h>

@interface NSString (HexConversion)
-(NSInteger)hexValue;
@end
\end{lstlisting}

%<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">NSString-HexConversion.m</span></span></div>
\begin{lstlisting}
#import "NSString-HexConversion.h"
#import <CoreFoundation/CFString.h>
#include <stdlib.h>

@implementation NSString (HexConversion)

-(NSInteger)hexValue
{
  CFStringRef cfSelf = (CFStringRef)self;
  UInt8 buffer[64];
  const char *cptr;

  if((cptr = CFStringGetCStringPtr(cfSelf, kCFStringEncodingMacRoman)) == NULL) {
    CFRange range     = CFRangeMake(0L, CFStringGetLength(cfSelf));
    CFIndex usedBytes = 0L;
    CFStringGetBytes(cfSelf, range, kCFStringEncodingUTF8, '?', false, buffer, 60L,
                     &usedBytes);
    buffer[usedBytes] = 0;
    cptr              = (const char *)buffer;
  }

  return((NSInteger)strtol(cptr, NULL, 16));
}

@end
\end{lstlisting}

\begin{RKLSeeAlso}
  \item \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man3/strtol.3.html}{strtol(3)}
  \item \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html\#//apple\_ref/occ/instm/NSString/intValue}{- intValue}
  \item \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html\#//apple\_ref/occ/instm/NSString/doubleValue}{- doubleValue}
\end{RKLSeeAlso}

\section{Text Files}

\begin{tabular}{|l|l|}\hline
\rowcolor[gray]{0.8862745} \Bd{Description} & \Bd{Regex} \\\hline
Empty Line & \Regex{(?m:\textasciicircum{}\$)}  \\\hline
Empty or Whitespace Only Line & \Regex{(?m-s:\textasciicircum{}\textbackslash{}s\*\$)}  \\\hline
Strip Leading Whitespace & \Regex{(?m-s:\textasciicircum{}\textbackslash{}s*(.*?)\$)}  \\\hline
Strip Trailing Whitespace & \Regex{(?m-s:\textasciicircum{}(.*?)\textbackslash{}s*\$)}  \\\hline
Strip Leading and Trailing Whitespace & \Regex{(?m-s:\textasciicircum{}\textbackslash{}s*(.*?)\textbackslash{}s*\$)}  \\\hline
Quoted String, Can Span Multiple Lines, May Contain \ConsoleText{\textbackslash{}"} & \Regex{"(?:[\textasciicircum{}"\textbackslash{}\textbackslash{}]*+|\textbackslash{}\textbackslash{}.)*"}  \\\hline
Quoted String, Single Line Only, May Contain \ConsoleText{\textbackslash{}"} & \Regex{"(?:[\textasciicircum{}"\textbackslash{}\textbackslash{}\textbackslash{}r\textbackslash{}n]*+|\textbackslash{}\textbackslash{}[\textasciicircum{}\textbackslash{}r\textbackslash{}n])*"}  \\\hline
HTML Comment & \Regex{(?s:<--.*?-->)}  \\\hline
Perl / Shell Comment & \Regex{(?m-s:\#.*\$)}  \\\hline
C, C++, or ObjC Comment & \Regex{(?m-s://.*\$)}  \\\hline
C, C++, or ObjC Comment and Leading Whitespace & \Regex{(?m-s:\textbackslash{}s*//.*\$)}  \\\hline
C, C++, or ObjC Comment & \Regex{(?s:/\textbackslash{}*.*?\textbackslash{}*/)}  \\\hline
\end{tabular}

\subsection{The Newline Debacle}

Unfortunately, when processing text files, there is no standard 'newline' character or character sequence.  Today this most commonly surfaces when converting text between Microsoft Windows / MS-DOS and Unix / \MacOSX{}.  The reason for the proliferation of newline standards is largely historical and goes back many decades.  Below is a table of the dominant newline character sequence 'standards':

\begin{tabular}{|l|l|l|l|l|}\hline
\rowcolor[gray]{0.8862745} \Bd{Description} & \Bd{Sequence} & \Bd{C String} & \Bd{Control} & \Bd{Common Uses}  \\\hline
Line Feed & \ConsoleText{\textbackslash{}u000A} & \ConsoleText{\textbackslash{}n} & \ConsoleText{\textasciicircum{}J} & Unix, Amiga, \MacOSX{}{} \\\hline
Vertical Tab & \ConsoleText{\textbackslash{}u000B} & \ConsoleText{\textbackslash{}v} & \ConsoleText{\textasciicircum{}K} &    \\\hline
Form Feed & \ConsoleText{\textbackslash{}u000C} & \ConsoleText{\textbackslash{}f} & \ConsoleText{\textasciicircum{}L} &    \\\hline
Carriage Return & \ConsoleText{\textbackslash{}u000D} & \ConsoleText{\textbackslash{}r} & \ConsoleText{\textasciicircum{}M} & Apple ][, Mac OS \textlesseq{} 9  \\\hline
Next Line (NEL) & \ConsoleText{\textbackslash{}u0085} &   &  & IBM / EBCDIC  \\\hline
Line Separator & \ConsoleText{\textbackslash{}u2028} &   &  & Unicode  \\\hline
Paragraph Separator & \ConsoleText{\textbackslash{}u2029} &   &  & Unicode  \\\hline
Carriage Return + Line Feed & \ConsoleText{\textbackslash{}u000D\textbackslash{}u000A} & \ConsoleText{\textbackslash{}r\textbackslash{}n} & \ConsoleText{\textasciicircum{}M\textasciicircum{}J} & MS-DOS, Windows  \\\hline
\end{tabular}\vskip 4pt plus 2pt minus 2pt
  
Ideally, one should be flexible enough to accept any of these character sequences if one has to process text files, especially if the origin of those text files is not known.  Thankfully, regular expressions excel at just such a task.  Below is a regular expression pattern that will match any of the above character sequences.  This is also the character sequence that the metacharacter \Regex{\$} matches.\par\vskip 4pt plus 2pt minus 2pt

\begin{tabularx}{0.94\textwidth}{|l|l|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Description} & \Bd{Regex} & \Bd{Notes}  \\\hline
Any newline & \Regex{(?:\textbackslash{}r\textbackslash{}n|[\textbackslash{}n\textbackslash{}v\textbackslash{}f\textbackslash{}r\textbackslash{}x85\textbackslash{}p\{Zl\}\textbackslash{}p\{Zp\}])} & UTS \#18 recommended. Character sequence that \Regex{\$} matches.  \\\hline
\end{tabularx}\vskip 4pt plus 2pt minus 2pt

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://www.unicode.org/reports/tr18/\#Line\_Boundaries}{UTS \#18: Unicode Regular Expressions - Line Boundaries}
  \item \RKLSectionHref{http://en.wikipedia.org/wiki/Newline}{Wikipedia - Newline}
\end{RKLSeeAlso}

\subsection{Matching the Beginning and End of a Line}

It is often necessary to work with the individual lines of a file. There are two regular expression metacharacters, \Regex{\textasciicircum{}} and \Regex{\$}, that match the \It{beginning} and \It{end} of a line, respectively. However, exactly what is matched by \Regex{\textasciicircum{}} and \Regex{\$} depends on whether or not the \RegexDef{multi-line} option is enabled for the regular expression, which by default is disabled. It can be enabled for the entire regular expression by passing \RKLCodeRef{RKLMultiline}{RKLMultiline} via the \Code{options:} method argument, or within the regular expression using the options syntax\textendash{} \Regex{(?m:}\textellipsis{}\Regex{)}.

If \RegexDef{multi-line} is \BdIt{disabled}, then \Regex{\textasciicircum{}} and \Regex{\$} match the beginning and end of the entire string.  If there is a \RegexDef{newline} character sequence at the very end of the string, then \Regex{\$} will match the character just before the \RegexDef{newline} character sequence.  Any \RegexDef{newline} character sequences in the middle of the string will \BdIt{not} be matched.

If \RegexDef{multi-line} is \BdIt{enabled}, then \Regex{\textasciicircum{}} and \Regex{\$} match the beginning and end of a line, where the end of a line is the \RegexDef{newline} character sequence.  The metacharacter \Regex{\textasciicircum{}} matches either the first character in the string, or the first character following a \RegexDef{newline} character sequence.  The metacharacter \Regex{\$} matches either the last character in the string, or the character just before a \RegexDef{newline} character sequence.

\subsection{Creating a \Code{NSArray} Containing Every Line in a String}

A common text processing pattern is to process a file one line at a time.  Using the recommended regular expression for matching any newline and the \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{componentsSeparatedByRegex:} method, you can easily create a \Code{NSArray} containing every line in a file and process it one line at a time:

%<div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Process every line\textellipsis{}</span></span></div>
\begin{lstlisting}[escapeinside=``]
NSString *fileNameString = @"example";
NSString *regexString    = @"(?:\r\n|[\n\v\f\r\302\205\\p{Zl}\\p{Zp}])";
NSError  *error          = NULL;
NSString *fileString     = [NSString stringWithContentsOfFile:fileNameString
                                                 usedEncoding:NULL
                                                        error:&error];

if(fileString) {
  NSArray *linesArray = [fileString componentsSeparatedByRegex:regexString];

  for(NSString *lineString in linesArray) { // ObjC 2.0 for`\texttt{\textit{…}}`in loop.
    // Per line processing.

  }
} else {
  NSLog(@"Error reading file '%@'", fileNameString);
  if(error) { NSLog(@"Error: %@", error); }
}
\end{lstlisting}

The \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{componentsSeparatedByRegex:} method effectively 'chops off' the matched regular expression, or in this case any newline character.  In the example above, within the \Code{for\textellipsis{}in} loop, \Code{lineString} will not have a newline character at the end of the string.

\labeledsubsection{RegexKitLiteCookbook_ParsingCSVData}{Parsing CSV Data}

\begin{tabularx}{0.725\textwidth}{|l|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Description} & \Bd{Regex} \\\hline
Split CSV line & \Regex{,(?=(?:(?:[\textasciicircum{}"\textbackslash{}\textbackslash{}]*+|\textbackslash{}\textbackslash{}")*"(?:[\textasciicircum{}"\textbackslash{}\textbackslash{}]*+|\textbackslash{}\textbackslash{}")*")*\RegexBreak{}(?!(?:[\textasciicircum{}"\textbackslash{}\textbackslash{}]*+|\textbackslash{}\textbackslash{}")*"(?:[\textasciicircum{}"\textbackslash{}\textbackslash{}]*+|\textbackslash{}\textbackslash{}")*\$))}\\\hline
\end{tabularx}%\vskip 4pt plus 2pt minus 2pt

This regular expression essentially works by ensuring that there are an even number of unescaped \Regex{"} quotes following a \Regex{,} comma.  This is done by using \It{look-head assertions}.  The first \It{look-head assertion}, \Regex{(?=}, is a pattern that matches zero or more strings that contain two \Regex{"} characters.  Then, a \It{negative look-head assertion} matches a single, unpaired \Regex{"} quote character remaining at the \Regex{\$} end of the line. It also uses \It{possessive matches} in the form of \Regex{*+} for speed, which prevents the regular expression engine from backtracking excessively. It's certainly not a beginners regular expression.

The following is used as a substitute for a CSV data file in the example below.

%<div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Example CSV data\textellipsis{}</span></span></div><span class="printOnly"><br></span>
\begin{lstlisting}
NSString *csvFileString = @"RegexKitLite,1.0,\"Mar 23, 2008\",27004\n"
                          @"RegexKitLite,1.1,\"Mar 28, 2008\",28081\n"
                          @"RegexKitLite,1.2,\"Apr 01, 2008\",28765\n"
                          @"RegexKitLite,2.0,\"Jul 07, 2008\",40569\n"
                          @"RegexKitLite,2.1,\"Jul 12, 2008\",40660\n";
\end{lstlisting}

%\RKLXXX{Think about converting to 4.0 blocks.}

This example really highlights the power of regular expressions when it comes to processing text. It takes just 17 lines, which includes comments, to parse a CSV data file of any newline type and create a \It{row} by \It{column} of \Code{NSArray} values of the results while correctly handling \Regex{"} quoted values, including escaped \Regex{\textbackslash{}"} quotes.

%<div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">Parse CSV data\textellipsis{}</span></span></div><span class="printOnly"><br></span>
\begin{lstlisting}[escapeinside=``]
NSString   *newlineRegex      = @"(?:\r\n|[\n\v\f\r\\x85\\p{Zl}\\p{Zp}])";
NSString   *splitCSVLineRegex = @",(?=(?:(?:[^\"\\\\]*+|\\\\\")*\""
                                @"(?:[^\"\\\\]*+|\\\\\")*\")*"
                                @"(?!(?:[^\"\\\\]*+|\\\\\")*\""
                                @"(?:[^\"\\\\]*+|\\\\\")*$))";

// Create a NSArray of every line in csvFileString.
NSArray *csvLinesArray = [csvFileString componentsSeparatedByRegex:newlineRegex];

// Create an id array to hold the comma split line results.
id          splitLines[[csvLinesArray count]]; // C99 variable length array.
NSUInteger  splitLinesIndex = 0UL;             // Index of next splitLines[] member.

for(NSString *csvLineString in csvLinesArray) {                // ObjC 2 for`\texttt{\textit{…}}`in loop.
  if([csvLineString isMatchedByRegex:@"^\\s*$"]) { continue; } // Skip empty lines.
  splitLines[splitLinesIndex++] =
      [csvLineString componentsSeparatedByRegex:splitCSVLineRegex];
}

// Gather up all the individual comma split results in to a single NSArray.
NSArray *splitLinesArray = [NSArray arrayWithObjects:&splitLines[0]
                                               count:splitLinesIndex];
\end{lstlisting}

\section{Network and URL}


\begin{tabularx}{\textwidth}{|p{18ex}|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Description} & \Bd{Regex}  \\\hline
HTTP & \Regex{\textbackslash{}bhttps?://[a-zA-Z0-9\textbackslash{}-.]+\RegexBreak{}(?:(?:/[a-zA-Z0-9\textbackslash{}-.\_?,'+\&\%\$=~*!():@\textbackslash{}\textbackslash{}]*)+)?} \\\hline
HTTP & \Regex{\textbackslash{}b(https?)://([a-zA-Z0-9\textbackslash{}-.]+)\RegexBreak{}((?:/[a-zA-Z0-9\textbackslash{}-.\_?,'+\&\%\$=~*!():@\textbackslash{}\textbackslash{}]*)+)?} \\\hline
HTTP & \Regex{\textbackslash{}b(https?)://(?:(\textbackslash{}S+?)(?::(\textbackslash{}S+?))?@)?([a-zA-Z0-9\textbackslash{}-.]+)\RegexBreak{}(?::(\textbackslash{}d+))?((?:/[a-zA-Z0-9\textbackslash{}-.\_?,'+\&\%\$=~*!():@\textbackslash{}\textbackslash{}]*)+)?} \\\hline
E-Mail & \Regex{\textbackslash{}b([a-zA-Z0-9\%\_.+\textbackslash{}-]+)@([a-zA-Z0-9.\textbackslash{}-]+?\textbackslash{}.[a-zA-Z]\{2,6\})\textbackslash{}b} \\\hline
Hostname & \Regex{\textbackslash{}b(?:[a-zA-Z0-9][a-zA-Z0-9\textbackslash{}-]\{0,61\}?[a-zA-Z0-9]\textbackslash{}.)+[a-zA-Z]\{2,6\}\textbackslash{}b} \\\hline
IP & \Regex{\textbackslash{}b(?:\textbackslash{}d\{1,3\}\textbackslash{}.)\{3\}\textbackslash{}d\{1,3\}\textbackslash{}b} \\\hline
IP with\newline{}Optional Netmask & \Regex{\textbackslash{}b((?:\textbackslash{}d\{1,3\}\textbackslash{}.)\{3\}\textbackslash{}d\{1,3\})(?:/(\textbackslash{}d\{1,2\}))?\textbackslash{}b} \\\hline
IP or Hostname & \Regex{\textbackslash{}b(?:(?:\textbackslash{}d\{1,3\}\textbackslash{}.)\{3\}\textbackslash{}d\{1,3\}|(?:[a-zA-Z0-9][a-zA-Z0-9\textbackslash{}-]\{0,61\}?\RegexBreak{}[a-zA-Z0-9]\textbackslash{}.)+[a-zA-Z]\{2,6\})\textbackslash{}b} \\\hline
\end{tabularx}\vskip 4pt plus 2pt minus 2pt


\subsection{Creating a \protect\texorpdfstring{\Code{NSDictionary}}{NSDictionary} of URL Information}

The following example demonstrates how to match several fields in a URL and create a \Code{NSDictionary} with the extracted results.  Only the capture groups that result in a successful match will create a corresponding key in the dictionary.

%\RKLXXX{Convert to new RKL4.0 way.}

%<div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">HTTP URL\textellipsis{}</span></span></div>
\begin{lstlisting}
NSString *searchString = 
              @"http://johndoe:secret@www.example.com:8080/private/mail/index.html";
NSString *regexString  = 
              @"\\b(https?)://(?:(\\S+?)(?::(\\S+?))?@)?([a-zA-Z0-9\\-.]+)"
              @"(?::(\\d+))?((?:/[a-zA-Z0-9\\-._?,'+\\&%$=~*!():@\\\\]*)+)?";

if([searchString isMatchedByRegex:regexString]) {
  NSString *protocolString = [searchString stringByMatching:regexString capture:1L];
  NSString *userString     = [searchString stringByMatching:regexString capture:2L];
  NSString *passwordString = [searchString stringByMatching:regexString capture:3L];
  NSString *hostString     = [searchString stringByMatching:regexString capture:4L];
  NSString *portString     = [searchString stringByMatching:regexString capture:5L];
  NSString *pathString     = [searchString stringByMatching:regexString capture:6L];

  NSMutableDictionary *urlDictionary = [NSMutableDictionary dictionary];

  if(protocolString) { [urlDictionary setObject:protocolString forKey:@"protocol"]; }
  if(userString)     { [urlDictionary setObject:userString     forKey:@"user"];     }
  if(passwordString) { [urlDictionary setObject:passwordString forKey:@"password"]; }
  if(hostString)     { [urlDictionary setObject:hostString     forKey:@"host"];     }
  if(portString)     { [urlDictionary setObject:portString     forKey:@"port"];     }
  if(pathString)     { [urlDictionary setObject:pathString     forKey:@"path"];     }

  NSLog(@"urlDictionary: %@", urlDictionary);
}
\end{lstlisting}

\RegexKitLite{ 4.0} adds a new method, \Code{dictionaryByMatchingRegex:\textellipsis{}}, that makes the creation of\DLBRK{} \Code{NSDictionary} objects like this much easier, as the following example demonstrates:

%<div class="box sourcecode"><div class="metainfo noPrintBorder"><span class="entry description"><span class="item meta">\RegexKitLite{}</span> &ge; 4.0 example\textellipsis{}</span></span></div>
\begin{lstlisting}
NSString     *searchString  = 
                @"http://johndoe:secret@www.example.com:8080/private/mail/index.html";

NSString     *regexString   = 
                @"\\b(https?)://(?:(\\S+?)(?::(\\S+?))?@)?([a-zA-Z0-9\\-.]+)"
                @"(?::(\\d+))?((?:/[a-zA-Z0-9\\-._?,'+\\&%$=~*!():@\\\\]*)+)?";

NSDictionary *urlDictionary = NULL;

urlDictionary = [searchString dictionaryByMatchingRegex:regexString
                                    withKeysAndCaptures:@"protocol", 1,
                                                        @"user",     2,
                                                        @"password", 3,
                                                        @"host",     4,
                                                        @"port",     5,
                                                        @"path",     6,
                                                        NULL];

if(urlDictionary != NULL) {
  NSLog(@"urlDictionary: %@", urlDictionary);
}
\end{lstlisting}

\RKLBoxNote{Other than the difference in mutability for the dictionary containing the result, the \RegexKitLite{ 4.0} \Code{dictionaryByMatchingRegex:\textellipsis{}} example produces the same result as the more verbose, \HardNobr{pre-4.0} example.}

These examples can form the basis of a function or method that takes a \Code{NSString} as an argument and returns a \Code{NSDictionary} as a result, maybe even as a category addition to \Code{NSString}.  The following is the output when the examples above are compiled and run:


\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{./http_example}\ReturnKey{}
2008-09-01 10:57:55.245 test_nsstring[31306:807] urlDictionary: \{
    host = "www.example.com";
    password = secret;
    path = "/private/mail/index.html";
    port = 8080;
    protocol = http;
    user = johndoe;
\}
shell% \ShellCursor{}
\end{Verbatim}

\labeledchapter{AddingRegexKitLitetoyourProject}{Adding \protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} to your Project}

\RKLBoxNote{The following outlines a typical set of steps that one would perform. This is not the only way, nor the required way to add \RegexKitLite{} to your application.  They may not be correct for your project as each project is unique.  They are an overview for those unfamiliar with adding additional shared libraries to the list of libraries your application links against.}

\section*{Outline of Required Steps}

The following outlines the steps required to use \RegexKitLite{} in your project.

\begin{RKLBulletList}
  \item Linking your application to the ICU dynamic shared library.
  \item Adding the \File{RegexKitLite.m} and \File{RegexKitLite.h} files to your project and application target.
  \item Import the \File{RegexKitLite.h} header.
\end{RKLBulletList}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/DeveloperTools/Conceptual/XcodeBuildSystem/500-Linking/bs\_linking.html}{Xcode Build System Guide - Linking}
\end{RKLSeeAlso}

\labeledsection{AddingRegexKitLitetoyourProject_AddingRegexKitLiteusingXcode}{Adding \protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} using Xcode}

\RKLBoxImportant{These instructions apply to Xcode versions 2.4.1 and 3.0.  Other versions should be similar, but may vary for specific details.}

Unfortunately, adding additional dynamic shared libraries that your application links to is not a straightforward process in Xcode, nor is there any recommended standard way.  Two options are presented below\textendash{} the first is the 'easy' way that alters your applications Xcode build settings to pass an additional command line argument directly to the linker.  The second option attempts to add the ICU dynamic shared library to the list of resources for your project and configuring your executable to link against the added resource.

The 'easy' way is the recommended way to link against the ICU dynamic shared library.

\subsection{The Easy Way To Add The ICU Library}

\begin{enumerate}

  \item First, determine the build settings layer of your project that should have altered linking configuration change applied to.  The build settings in Xcode are divided in to layers and each layer inherits the build settings from the layer above it. The top, global layer is \MenuText{Project Settings}, followed by \MenuText{Target Settings}, and finally the most specific layer \MenuText{Executable Settings}
.  If your project is large enough to have multiple targets and executables, you probably have an idea which layer is appropriate.  If you are unsure or unfamiliar with the different layers, \MenuText{Target Settings} is recommended.

  \item Select the appropriate layer from the \MenuText{Project} menu.  If you are unsure, \MenuText{Project \MenuRightArrow{} Edit Active Target} is recommended.

  \item Select \MenuText{Build} from the tab near the top of the \MenuText{Target Info} window.  Find the \MenuText{Other Linker Flags} build setting from the many build settings available and edit it. Add \HardNobr{\ConsoleText{-licucore}} \Bd{[}\textit{dash ell icucore} as a single word, without spaces\Bd{]}.  If there are already other flags present, it is recommended that you add \HardNobr{\ConsoleText{-licucore}} to the end of the existing flags.

    \RKLBoxImportant{If other linker flags are present, there must be at least one space separating \HardNobr{\ConsoleText{-licucore}} from the other linker flags. For example, \HardNobr{\ConsoleText{-flag1 -licucore -flag2}}}

    \RKLBoxNote{The \MenuText{Configuration} drop down menu controls which build configuration the changes you make are applied to. \MenuText{All Configurations} should be selected if this is the first time your are making these changes.}

  \item Follow the \RKLSectionRef{AddingTheRegexKitLiteSourceFilesToYourProject}{Add The \RegexKitLite{} Source Files To Your Project} steps \vpagerefx[below][{on page \pageref*{AddingTheRegexKitLiteSourceFilesToYourProject}}]{AddingTheRegexKitLiteSourceFilesToYourProject}.

\end{enumerate}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/DeveloperTools/Conceptual/XcodeBuildSystem/300-Build\_Settings/bs\_build\_settings.html}{Xcode Build System Guide - Build Settings}
\end{RKLSeeAlso}

\subsection{The Hard Way To Add The ICU Library}

\begin{enumerate}

  \item First, add the ICU dynamic shared library to your Xcode project.  You may choose to add the library to any group in your project, and which groups are created by default is dependent on the template type you chose when you created your project.  For a typical Cocoa application project, a good choice is the \MenuText{Frameworks} group.  To add the ICU dynamic shared library, control/right-click on the \MenuText{Framework} group and choose \MenuText{Add \MenuRightArrow{} Existing Files\textellipsis{}}

  \item {Next, you will need to choose the ICU dynamic shared library file to add.  Exactly which file to choose depends on your project, but a fairly safe choice is to select \File{/Developer/SDKs/MacOSX10.6.sdk/\RKLLeftHookDiscretionaryBreak{}usr/lib/libicucore.dylib}. You may have installed your developer tools in a different location than the default \File{/Developer} directory, and the \MacOSX{}{} SDK version should be the one your project is targeting, typically the latest one available.}

  \item Then, in the dialog that follows, make sure that \MenuText{Copy items into\textellipsis{}} is unselected.  Select the targets you will be using \RegexKitLite{} in and then click \MenuText{Add} to add the ICU dynamic shared library to your project.

  \item Once the ICU dynamic shared library is added to your project, you will need to add it to the libraries that your executable is linked with.  To do so, expand the \MenuText{Targets} group, and then expand the executable targets you will be using \RegexKitLite{} in.  You will then need to select the \File{libicucore.dylib} file that you added in the previous step and drag it in to the \MenuText{Link Binary With Libraries} group for each executable target that you will be using \RegexKitLite{} in.  The order of the files within the \MenuText{Link Binary With Libraries} group is not important, and for a typical Cocoa application the group will contain the \File{Cocoa.framework} file.

\end{enumerate}

\labeledsubsection{AddingTheRegexKitLiteSourceFilesToYourProject}{Add The \protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} Source Files To Your Project}

\begin{enumerate}

  \item Next, add the \RegexKitLite{} source files to your Xcode project.  In the \HardNobr{\MenuText{Groups \& Files}} outline view on the left, control/right-click on the group that would like to add the files to, then select \HardNobr{\MenuText{Add \MenuRightArrow{} Existing Files\textellipsis{}}}

\RKLBoxNote{You can perform the following steps once for each file (\File{RegexKitLite.h} and \linebreak \File{RegexKitLite.m}), or once by selecting both files from the file dialog.}

  \item Select the \File{RegexKitLite.h} and / or \File{RegexKitLite.m} file from the file chooser dialog.

  \item The next dialog will present you with several options.  If you have not already copied the \RegexKitLite{} files in to your projects directory, you may want to click on the \MenuText{Copy items into\textellipsis{}} option.  Select the targets that you would like add the \RegexKitLite{} functionality to.

  \item Finally, you will need to include the \File{RegexKitLite.h} header file.  The best way to do this is very dependent on your project.  If your project consists of only half a dozen source files, you can add:

\begin{lstlisting}
#import "RegexKitLite.h"
\end{lstlisting}

manually to each source file that makes uses of \RegexKitLite{s} features. If your project has grown beyond this, you've probably already organized a common "master" header to include to capture headers that are required by nearly all source files already.

\end{enumerate}

\labeledsection{AddingRegexKitLitetoyourProject_AddingRegexKitLiteusingtheShell}{Adding \protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} using the Shell}

Using \RegexKitLite{} from the shell is also easy.  Again, you need to add the header \Code{\#import} to the appropriate source files.  Then, to link to the ICU library, you typically only need to add \ConsoleText{-licucore}, just as you would any other library.  Consider the following example:

%<div class="box sourcecode"><div class="metainfo printShadow"><span class="entry filename"><span class="item meta">File name:</span><span class="item info">link\_example.m</span></span></div>
\begin{lstlisting}
#import <Foundation/NSObjCRuntime.h>
#import <Foundation/NSAutoreleasePool.h>
#import "RegexKitLite.h"

int main(int argc, char *argv[]) {
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  // Copyright COPYRIGHT_SIGN APPROXIMATELY_EQUAL_TO 2008
  // Copyright \u00a9 \u2245 2008

  char     *utf8CString =  "Copyright \xC2\xA9 \xE2\x89\x85 2008";
  NSString *regexString = @"Copyright (.*) (\\d+)";

  NSString *subjectString = [NSString stringWithUTF8String:utf8CString];
  NSString *matchedString = [subjectString stringByMatching:regexString capture:1L];

  NSLog(@"subject: \"%@\"", subjectString);
  NSLog(@"matched: \"%@\"", matchedString);

  [pool release];
  return(0);
}
\end{lstlisting}

Compiled and run from the shell:

\begin{Verbatim}[commandchars=\\\{\}]
shell% \Bd{cd examples}\ReturnKey{}
shell% \Bd{gcc -g -I.. -o link\_example link\_example.m ../RegexKitLite.m \textbackslash{}}
       \Bd{-framework Foundation -licucore}\ReturnKey{}
shell% \Bd{./link_example}\ReturnKey{}
2008-03-14 03:52:51.187 test[15283:807] subject: "Copyright \textcopyright{} \textapproximatelyequalto{} 2008"
2008-03-14 03:52:51.269 test[15283:807] matched: "\textcopyright{} \textapproximatelyequalto{}"
shell% \ShellCursor{}
\end{Verbatim}

\labeledchapter{RegexKitLiteNSStringAdditionsReference}{\protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} NSString Additions Reference}


\begin{tabular}{ll}
\Bd{Extends by category} & \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/index.html}{NSString}, \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSMutableString\_Class/index.html}{NSMutableString} \\
\Bd{\RegexKitLite{}}     & \RKLVersion{} \\
\Bd{Declared in}         & RegexKitLite.h \\
\Bd{Companion guides}    & \RKLHref{http://userguide.icu-project.org/strings/regexp}{ICU User Guide - Regular Expressions} \\
\end{tabular}

\section{Overview}

\RegexKitLite{} is not meant to be a full featured regular expression framework. Because of this, it provides only the basic primitives needed to create additional functionality. It is ideal for developers who:

\begin{RKLBulletList}
  \item Developing applications for the iPhone.
  \item Have modest regular expression needs.
  \item Require a very small footprint.
  \item Unable or unwilling to add additional, external frameworks.
  \item Deal predominantly in \UTF{16} encoded Unicode strings.
  \item Require the enhanced word breaking functionality provided by the ICU library.
\end{RKLBulletList}

\RegexKitLite{} consists of only two files, the header file \File{RegexKitLite.h} and \File{RegexKitLite.m}.  The only other requirement is to link with the ICU library that comes with \MacOSX{}.  No new classes are created, all functionality is provided as a category extension to the \Code{NSString} and \Code{NSMutableString} classes.

\begin{RKLSeeAlso}
  \item \RKLSectionPageRef{IntroductiontoRegexKitLite}{\RegexKitLite{} Guide}
  \item \RKLSectionPageRef{ICUSyntax_ICURegularExpressionSyntax}{ICU Regular Expression Syntax}
  \item \RKLSectionPageRef{AddingRegexKitLitetoyourProject}{Adding \RegexKitLite{} to your Project}
  \item \RKLSectionPageRef{LicenseInformation}{License Information}
  \item \RKLSectionHref{http://regexkit.sourceforge.net/}{RegexKit Framework}
  \item \RKLSectionHref{http://site.icu-project.org/}{International Components for Unicode}
  \item \RKLSectionHref{http://www.unicode.org/}{Unicode Home Page}
\end{RKLSeeAlso}

\labeledsubsection{NSString_RegexKitLiteAdditions__CompileTimePreprocessorTunables}{Compile Time Preprocessor Tunables}

The settings listed below are implemented using the C Preprocessor.  Some of the setting are simple boolean \Code{enabled} or \Code{disabled} settings, while others specify a value, such as the number of cached compiled regular expressions.  There are several ways to alter these settings, but if you are not familiar with this style of compile time configuration settings and how to alter them using the C Preprocessor, it is recommended that you use the default values provided.

\begin{tabularx}{\textwidth}{|>{\hsize=0.4\hsize}X|l|>{\hsize=1.6\hsize}X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Setting} & \Bd{Default} & \Bd{Description} \\\hline
\CPPFlag{NS\_\DBrk{}BLOCK\_\DBrk{}ASSERTIONS} & \It{n/a} & \RegexKitLite{} contains a number of extra run-time assertion checks that can be disabled with this flag.  The standard \File{NSException.h} assertion macros are not used because of the multithreading lock.  This flag is typically set for \MenuText{Release} style builds where the additional error checking is no longer necessary. \\\hline
\CPPFlag{RKL\_\DBrk{}APPEND\_\DBrk{}TO\_\DBrk{}ICU\_\DBrk{}FUNCTIONS} & \It{None} & This flag is useful if you are supplying your own version of the ICU library. When set, this preprocessor define causes the ICU functions used by \RegexKitLite{} to have the value of \CPPFlag{RKL\_APPEND\_TO\_ICU\_FUNCTIONS} appended to them. For example, if \CPPFlag{RKL\_APPEND\_TO\_ICU\_FUNCTIONS} is set to \Code{\_4\_0} (i.e., \Code{-DRKL\_APPEND\_TO\_ICU\_FUNCTIONS=\_4\_0}), it would cause \linebreak \Code{uregex\_find()} to become \Code{uregex\_find\_4\_0()}. \\\hline
\CPPFlag{RKL\_\DBrk{}BLOCKS} & \It{Automatic} & Enables blocks support. This feature is automatically enabled if \CPPFlag{NS\_BLOCKS\_AVAILABLE} is set to \Code{1}, which is typically set if support for blocks is appropriate.  At the time of this writing, this typically means that the Xcode setting for the minimum version of \MacOSX{}{} supported must be 10.6. This feature may be explicitly disabled under all circumstances by setting its value to \Code{0}, or alternatively it can be explicitly enabled under all circumstances by setting its value to \Code{1}.  The behavior is undefined if \CPPFlag{RKL\_BLOCKS} is set to \Code{1} and the compiler does not support the blocks language extension or if the run-time does not support blocks. \\\hline
\CPPFlag{RKL\_\DBrk{}CACHE\_\DBrk{}SIZE} & \Code{13} & \RegexKitLite{} uses a \HardNobr{4-way} set associative cache and \CPPFlag{RKL\_CACHE\_SIZE} controls the number of sets in the cache.  The total number of compiled regular expressions that can be cached is \HardNobr{\CPPFlag{RKL\_CACHE\_SIZE} * \Code{4},} for a default value of \Code{52}.  \CPPFlag{RKL\_CACHE\_SIZE} should always be a prime number to maximize the use of the cache. \\\hline
\CPPFlag{RKL\_\DBrk{}DTRACE} & \It{Disabled} & This preprocessor define controls whether or not \RegexKitLite{} provider DTrace probe points are enabled.  This feature may be explicitly disabled under all circumstances by setting its value to \Code{0}. \\\hline
\CPPFlag{RKL\_\DBrk{}FAST\_\DBrk{}MUTABLE\_\DBrk{}CHECK} & \It{Disabled} & Enables the use of the undocumented, private \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation} \linebreak \Code{\_\_CFStringIsMutable()} function to determine if the string to be searched is immutable.  This can significantly increase the number of matches per second that can be performed on immutable strings since a number of mutation checks can be safely skipped. \\\hline
\CPPFlag{RKL\_\DBrk{}FIXED\_\DBrk{}LENGTH} & \Code{2048} & Sets the size of the fixed length \UTF{16} conversion cache buffer.  Strings that need to be converted to \UTF{16} that have a length less than this size will use the fixed length conversion cache.  Using a fixed sized buffer for all small strings means less \Code{malloc()} overhead, heap fragmentation, and reduces the chances of a memory leak occurring. \\\hline
\CPPFlag{RKL\_\DBrk{}METHOD\_\DBrk{}PREPEND} & \It{None} & When set, this preprocessor define causes the \RegexKitLite{} methods defined in \File{RegexKitLite.h} to have the value of \CPPFlag{RKL\_METHOD\_PREPEND} prepended to them.  For example, if \CPPFlag{RKL\_METHOD\_PREPEND} is set to \Code{xyz\_} (i.e., \ConsoleText{-DRKL\_METHOD\_PREPEND=xyz\_}), it would cause \RKLCodePageRef{NSString_RegexKitLiteAdditions__.clearStringCache}{clearStringCache} to become \Code{xyz\_clearStringCache}. \\\hline
\end{tabularx}

\begin{tabularx}{\textwidth}{|>{\hsize=0.4\hsize}X|l|>{\hsize=1.6\hsize}X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Setting} & \Bd{Default} & \Bd{Description} \\\hline
\CPPFlag{RKL\_REGISTER\_\DBrk{}FOR\_\DBrk{}IPHONE\_\DBrk{}LOWMEM\_\DBrk{}NOTIFICATIONS} & \It{Automatic} & This preprocessor define controls whether or not extra code is included that attempts to automatically register with the \Code{NSNotificationCenter} for the \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/UIKit/Reference/UIApplication\_Class/Reference/Reference.html\#//apple\_ref/c/data/UIApplicationDidReceiveMemoryWarningNotification}{UIApplication\DBrk{}Did\DBrk{}Receive\DBrk{}Memory\DBrk{}Warning\DBrk{}Notification} notification.  This feature is automatically enabled if it can be determined at compile time that the iPhone is being targeted.  This feature may be explicitly disabled under all circumstances by setting its value to \Code{0}. \\\hline
\CPPFlag{RKL\_\DBrk{}STACK\_\DBrk{}LIMIT} & \Code{131072} & The maximum amount of stack space that will be used before switching to heap based allocations.  This can be useful for multithreading programs where the stack size of secondary threads is much smaller than the main thread. \\\hline
\end{tabularx}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Assertions/Tasks/AssertMacros.html}{Assertions and Logging - Using the Assertion Macros}%
\end{RKLSeeAlso}

\subsubsection{Fast Mutable Checks}

Setting \CPPFlag{RKL\_FAST\_MUTABLE\_CHECK} allows \RegexKitLite{} to quickly check if a string to search is immutable or not.  Every call to \RegexKitLite{} requires checking a strings \Code{hash} and \Code{length} values to guard against a string mutating and using invalid cached data.  If the same string is searched repeatedly and it is immutable, these checks aren't necessary since the string can never change while in use.  While these checks are fairly quick, it can add approximately 15 to 20 percent of extra overhead, and not performing the checks is always faster.

Since checking a strings mutability requires calling an undocumented, private \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation} function, \RegexKitLite{} takes extra precautions and does not use the function directly.  Instead, an internal, local stub function is created and called to determine if a string is mutable.  The first time this function is called, \RegexKitLite{} uses \Code{dlsym()} to look up the address of the \Code{\_\_CFStringIsMutable()} function.  If the function is found, \RegexKitLite{} will use it from that point on to determine if a string is immutable. However, if the function is not found, \RegexKitLite{} has no way to determine if a string is mutable or not, so it assumes the worst case that all strings are potentially mutable.  This means that the private \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation} \HardNobr{\Code{\_\_CFStringIsMutable()}} function can go away at any time and \RegexKitLite{} will continue to work, although with slightly less performance.

This feature is disabled by default, but should be fairly safe to enable due to the extra precautions that are taken.  If this feature is enabled and the \Code{\_\_CFStringIsMutable()} function is not found for some reason, \RegexKitLite{} falls back to its default behavior which is the same as if this feature was not enabled.

\subsubsection{iPhone Low Memory Notifications}

{\sloppy{}The \CPPFlag{RKL\_REGISTER\_FOR\_IPHONE\_LOWMEM\_NOTIFICATIONS} preprocessor define controls whether or not extra code is compiled in that automatically registers for the iPhone UIKit \RKLCodeHref{http://developer.apple.com/iphone/library/documentation/UIKit/Reference/UIApplication\_Class/Reference/Reference.html\#//apple\_ref/c/data/UIApplicationDidReceiveMemoryWarningNotification}{UIApplicationDid\DLBrk{}Receive\DLBRK{}Mem\DLBRk{}o\DLBrk{}ry\DLBrk{}Warn\DLBrk{}ing\DLBrk{}No\DLBrk{}ti\DLBrk{}fi\DLBrk{}ca\DLBrk{}tion} notification.  When enabled, an initialization function tagged with\DLBRK{} \Code{\_\_attribute\_\_((constructor))} is executed by the linker at load time which causes \RegexKitLite{} to\DLBRK{} check if the low memory notification symbol is available.  If the symbol is present then \RegexKitLite{} registers to receive the notification.  When the notification is received, \RegexKitLite{} will automatically call\DLBRK{} \RKLCodePageRef{NSString_RegexKitLiteAdditions__.clearStringCache}{clearStringCache} to flush the caches and return the memory used to hold any cached compiled regular expressions.}

This feature is normally automatically enabled if it can be determined at compile time that the iPhone is being targeted.  This feature is safe to enable even if the target is \MacOSX{}{} for the desktop.  It can also be explicitly disabled, even when targeting the iPhone, by setting \CPPFlag{RKL\_REGISTER\_FOR\_IPHONE\_LOWMEM\_NOTIFICATIONS} to \Code{0} (i.e., \ConsoleText{-DRKL\_REGISTER\_FOR\_IPHONE\_LOWMEM\_NOTIFICATIONS=0}).

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://developer.apple.com/iphone/library/documentation/Performance/Conceptual/ManagingMemory/Articles/MemoryAlloc.html\#//apple\_ref/doc/uid/20001881-SW1}{Memory Usage Performance Guidelines - Responding to Low-Memory Warnings in iPhone OS}
\end{RKLSeeAlso}

\subsubsection{Using \RegexKitLite{} with a Custom ICU Build}

The details of building and linking to a custom build of ICU will not be covered here.  ICU is a very large and complex library that can be configured and packaged in countless ways.  Building and linking your application to a custom build of ICU is \BdIt{non-trivial}.  Apple provides the full source to the version of ICU \linebreak that they supply with \MacOSX{}.  At the time of this writing, the latest version available was for \linebreak \HardNobr{\MacOSX{ 10.6.2}\textendash{}} \RKLHref{http://www.opensource.apple.com/tarballs/ICU/ICU-400.38.tar.gz}{\File{ICU-400.38.tar.gz}}.

\RegexKitLite{} provides the \CPPFlag{RKL\_APPEND\_TO\_ICU\_FUNCTIONS} C preprocessor define if you would like to use \RegexKitLite{} with a custom ICU build that you supply.  A custom version of ICU will typically have \linebreak the ICU version appended to all of its functions, and \CPPFlag{RKL\_APPEND\_TO\_ICU\_FUNCTIONS} allows you \linebreak to append that version to the ICU functions that \RegexKitLite{} calls.  For example, passing \linebreak \HardNobr{\ConsoleText{-DRKL\_APPEND\_TO\_ICU\_FUNCTIONS=\_4\_0}} to \ConsoleText{gcc} would cause the ICU function \Code{uregex\_find()} used by \RegexKitLite{} to be called as \Code{uregex\_find\_4\_0()}.

\labeledsubsection{NSStringRegexKitLiteAdditionsXcode3IntegratedDocumentation}{Xcode 3 Integrated Documentation}

This documentation is available in the Xcode DocSet format at the following URL:

\hspace{2.5ex}\Code{feed://regexkit.sourceforge.net/RegexKitLiteDocSets.atom}

For Xcode < 3.2, select \MenuText{Help \MenuRightArrow{} Documentation}. Then, in the lower left hand corner of the documentation window, there should be a gear icon with a drop down menu indicator which you should select and choose \MenuText{New Subscription\textellipsis{}} and enter the DocSet URL.

For Xcode \textgreatereq{} 3.2, select \MenuText{Xcode \MenuRightArrow{} Preferences\textellipsis{}}. Then select the \MenuText{Documentation} preference group, typically the right most group, and press \MenuText{Add Documentation Set Publisher\textellipsis{}} and enter the DocSet URL.

Once you have added the URL, a new group should appear, inside which will be the \RegexKitLite{} documentation with a \MenuText{Get} button.  Click on the \MenuText{Get} button and follow the prompts.

\RKLBoxNote{Xcode will ask you to enter an administrators password to install the documentation, which is explained \RKLHref{http://developer.apple.com/mac/library/documentation/DeveloperTools/Conceptual/Documentation\_Sets/070-Acquiring\_Documentation\_Sets\_Through\_Web\_Feeds/acquiring\_docsets.html\#//apple\_ref/doc/uid/TP40005266-CH10-SW9}{here}.}

\labeledsubsection{NSString_RegexKitLiteAdditions__CachedInformationandMutableStrings}{Cached Information and Mutable Strings}

While \RegexKitLite{} takes steps to ensure that the information it has cached is valid for the strings it searches, there exists the possibility that out of date cached information may be used when searching mutable strings.  For each compiled regular expression, \RegexKitLite{} caches the following information about the last \linebreak \Code{NSString} that was searched:

\begin{RKLBulletList}
  \item The strings \Code{length}, \Code{hash} value, and the pointer to the \Code{NSString} object.
  \item The pointer to the \UTF{16} buffer that contains the contents of the string, which may be an internal buffer if the string required conversion.
  \item The \Code{NSRange} used for the \Code{inRange:} parameter for the last search, and the \Code{NSRange} result for capture \Code{0} of that search.
\end{RKLBulletList}

An ICU compiled regular expression must be "set" to the text to be searched.  Before a compiled regular expression is used, the pointer to the string object to search, its \Code{hash}, \Code{length}, and the pointer to the \UTF{16} buffer is compared with the values that the compiled regular expression was last "set" to.  If any of these values are different, the compiled regular expression is reset and "set" to the new string.

If a \Code{NSMutableString} is mutated between two uses of the same compiled regular expression and its \Code{hash}, \Code{length}, or \UTF{16} buffer changes between uses, \RegexKitLite{} will automatically reset the compiled regular expression with the new values of the mutated string.  The results returned will correctly reflect the mutations that have taken place between searches.

It is possible that the mutations to a string can go undetected, however.  If the mutation keeps the \Code{length} the same, then the only way a change can be detected is if the strings \Code{hash} value changes.  For most mutations the \Code{hash} value will change, but it is possible for two different strings to share the same \Code{hash}.  This is known as a \It{hash collision}.  Should this happen, the results returned by \RegexKitLite{} may not be correct.

Therefore, if you are using \RegexKitLite{} to search \Code{NSMutableString} objects, and those strings may have mutated in such a way that \RegexKitLite{} is unable to detect that the string has changed, you must manually clear the internal cache to ensure that the results accurately reflect the mutations.  To clear the cached information for a specific string you send the instance a \RKLCodePageRef{NSString_RegexKitLiteAdditions__-flushCachedRegexData}{flushCachedRegexData} message:

\begin{lstlisting}
NSMutableString *aMutableString; // Assumed to be valid.
[aMutableString flushCachedRegexData];
\end{lstlisting}

To clear all of the cached information in \RegexKitLite{,} which includes all the cached compiled regular expressions along with any cached information and \UTF{16} conversions for strings that have been searched, you use the following class method:

\begin{lstlisting}
[NSString clearStringCache];
\end{lstlisting}

\RKLBoxWarning{When searching \Code{NSMutableString} objects that have mutated between searches, failure to clear the cache may result in undefined behavior.  Use \RKLCodePageRef{NSString_RegexKitLiteAdditions__-flushCachedRegexData}{flushCachedRegexData} to selectively clear the cached information about a \Code{NSMutableString} object.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__.clearStringCache}{+ clearStringCache}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-flushCachedRegexData}{- flushCachedRegexData}
\end{RKLSeeAlso}

\labeledsubsection{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{Block-based Enumeration Methods}

The \RegexKitLite{} Block-based enumeration methods are modeled after their \Code{NSString} counterparts.  There are a few differences, however.

\begin{RKLBulletList}
  \item \RegexKitLite{} does not support mutating a \Code{NSMutableString} object while it is under going Block-based enumeration.
  \item There is no support for concurrent enumeration.
\end{RKLBulletList}

While \RegexKitLite{} may not support mutating a \Code{NSMutableString} during Block-based enumeration, it does provide the means to create a new string from the \Code{NSString} object returned by the block used to enumerate the matches in a string, and in the case of \Code{NSMutableString}, to replace the contents of that \Code{NSMutableString} with the modified string at the end of the enumeration.  This functionality is available via the following methods:

\begin{RKLBulletList}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:}{- stringByReplacingOccurrencesOfRegex:usingBlock:} (\Code{NSString})
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:}{- replaceOccurrencesOfRegex:usingBlock:} (\Code{NSMutableString})
\end{RKLBulletList}

\subsubsection{Exception to the Cocoa Memory Management Rules for Block-based Enumeration}

The standard \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html}{Cocoa Memory Management Rules} specify that objects returned by a method, or in this case the objects passed to a Block, remain valid throughout the scope of the calling method.  Due to the potentially large volume of temporary strings that are created during a Block-based enumeration, \RegexKitLite{} makes an exception to this rule\textendash{} the strings passed to a Block via \Argument{capturedStrings}\Code{[]} are valid only until the closing brace of the Block:

\begin{lstlisting}
[searchString enumerateStringsMatchedByRegex:regex
                                  usingBlock:
 ^(NSInteger captureCount,
   NSString * const capturedStrings[captureCount],
   const NSRange capturedRanges[captureCount],
   volatile BOOL * const stop) {
   // Block code.
 } /* <- capturedStrings[] is valid only up to this point. */ ];
\end{lstlisting}

If you need to refer to a string past the closing brace of the Block, you need to send that string a \Code{retain} message.  Of course, it is not always necessary to explicitly send a \Argument{capturedStrings}\Code{[]} string a \Code{retain} message when you need it to exist past the closing brace of a Block\textendash{} adding a \Argument{capturedStrings}\Code{[]} string to a \Code{NSMutableDictionary} will send the string a \Code{retain} as a side effect of adding it to the dictionary.

Memory management during \RegexKitLite{} Block-based enumeration is conceptually similar to the following pseudo-code:

\begin{lstlisting}
NSInteger captureCount = [regex captureCount];

while(moreMatches) {
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];

  BOOL      stop = NO;
  NSRange   capturedRanges[captureCount];
  NSString *capturedStrings[captureCount];

  for(capture = 0L; capture < captureCount; capture++) {
    capturedRanges[capture]  = [searchString rangeOfRegex:regex capture:capture];
    capturedStrings[capture] = [searchString stringByMatching:regex capture:capture];
  }

  // The following line represents the execution of the user supplied Block.
  enumerationBlock(captureCount, capturedStrings, capturedRanges, &stop);
  // ... and this represents when the user supplied Block has finished / returned.

  [pool release]; // capturedStrings[] are sent a release at this point.
  if(stop != NO) { break; }
}
\end{lstlisting}

While conceptually and behaviorally similar, it is important to note that \RegexKitLite{} does not actually use or create autorelease pools when performing Block-based enumeration.  Instead, a \Code{CFMutableArray} object is used to accumulate the temporary string objects during an iteration, and at the start of an iteration, any previously accumulated temporary string objects are removed from the array.

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
  \item \RKLSectionPageRef{RegularExpressionEnumerationOptions}{Regular Expression Enumeration Options}
\end{RKLSeeAlso}

\subsection{Usage Notes}

\subsubsection{Convenience Methods}

For convenience methods where an argument is not present, the default value used is given below.

\begin{tabular}{|l|l|}\hline
\rowcolor[gray]{0.8862745} \Bd{Argument} & \Bd{Default Value} \\\hline
\Code{capture:} & \Code{0} \\\hline
\Code{options:} & \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} \\\hline
\Code{range:} & The entire range of the receiver. \\\hline
\Code{enumerationOptions:} & \RKLCodePageRef{RKLRegexEnumerationNoOptions}{RKLRegexEnumerationNoOptions} \\\hline
\end{tabular}

\subsubsection{Exceptions Raised}

Methods will raise an exception if their arguments are invalid, such as passing \Code{NULL} for a required parameter.  An invalid regular expression or \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} parameter will not raise an exception.  Instead, a \Code{NSError} object with information about the error will be created and returned via the address given with the optional \Argument{error} argument.  If information about the problem is not required, \Argument{error} may be \Code{NULL}.  For convenience methods that do not have an \Argument{error} argument, the primary method is invoked with \Code{NULL} passed as the argument for \Argument{error}.

\RKLBoxImportant{Methods raise \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSInvalidArgumentException}{NSInvalidArgumentException} if \Argument{regex} is \Code{NULL}, or if \Argument{capture} < \Code{0}, or is not valid for \Argument{regex}.}

\RKLBoxImportant{Methods raise \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSRangeException}{NSRangeException} if \Argument{range} exceeds the bounds of the receiver.}

\RKLBoxImportant{Methods raise \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSRangeException}{NSRangeException} if the receivers length exceeds the maximum value that can be represented by a signed \HardNobr{32-bit} integer, even on \HardNobr{64-bit} architectures.}

\RKLBoxImportant{Search and replace methods raise \RKLCodePageRef{RKLICURegexException}{RKLICURegexException} if \Argument{replacement} contains \Regex{\$}\Argument{n} capture references where \Argument{n} is greater than the number of capture groups in the regular expression \Argument{regex}.}

\begin{RKLSeeAlso}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
\end{RKLSeeAlso}

\begin{RKLTasks}

\begin{RKLTaskSection}{DTrace Probe Points}
  \item[\RKLCodePageRef{DTrace_RegexKitLiteProbePoints__compiledRegexCache}{RegexKitLite:::compiledRegexCache}] This probe point fires each time the compiled regular expression cache is accessed.
  \item[\RKLCodePageRef{DTrace_RegexKitLiteProbePoints__utf16ConversionCache}{RegexKitLite:::utf16ConversionCache}] This probe point fires each time the \UTF{16} conversion cache is accessed.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Clearing Cached Information}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__.clearStringCache}{+ clearStringCache}] Clears the cached information about strings.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-flushCachedRegexData}{- flushCachedRegexData}] Clears any cached information about the receiver.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Determining the Number of Captures}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__.captureCountForRegex:}{+ captureCountForRegex:}~~\Deprecated{Deprecated in \RegexKitLite{ 3.0}}] Returns the number of captures that \Argument{regex} contains.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__.captureCountForRegex:options:error:}{+ captureCountForRegex:options:error:}~~\Deprecated{Deprecated in \RegexKitLite{ 3.0}}] Returns the number of captures that \Argument{regex} contains.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCount}{- captureCount}] Returns the number of captures that the receiver contains.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:}{- captureCountWithOptions:error:}] Returns the number of captures that the receiver contains.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Finding all Captures of all Matches}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:}{- arrayOfCaptureComponentsMatchedByRegex:}] Returns an array containing all the matches from the receiver that were matched by the regular expression \Argument{regex}. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:range:}{- arrayOfCaptureComponentsMatchedByRegex:range:}] Returns an array containing all the matches from the receiver that were matched by the regular expression \Argument{regex} within \Argument{range}. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:options:range:error:}{- arrayOfCaptureComponentsMatchedByRegex:options:range:error:}] Returns an array containing all the matches from the receiver that were matched by the regular expression \Argument{regex} within \Argument{range} using \Argument{options}. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Getting all the Captures of a Match}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:}{- captureComponentsMatchedByRegex:}] Returns an array containing the substrings matched by each capture group present in \Argument{regex} for the first match of \Argument{regex} in the receiver.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:range:}{- captureComponentsMatchedByRegex:range:}] Returns an array containing the substrings matched by each capture group present in \Argument{regex} for the first match of \Argument{regex} within \Argument{range} of the receiver.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:options:range:error:}{- captureComponentsMatchedByRegex:options:range:error:}] Returns an array containing the substrings matched by each capture group present in \Argument{regex} for the first match of \Argument{regex} within \Argument{range} of the receiver using \Argument{options}.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Finding all Matches}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:}{- componentsMatchedByRegex:}] Returns a \Code{NSArray} containing all the substrings from the receiver that were matched by the regular expression \Argument{regex}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:capture:}{- componentsMatchedByRegex:capture:}] Returns a \Code{NSArray} containing all the substrings from the receiver that were matched by capture number \Argument{capture} from the regular expression \Argument{regex}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:range:}{- componentsMatchedByRegex:range:}] Returns a \Code{NSArray} containing all the substrings from the receiver that were matched by the regular expression \Argument{regex} within \Argument{range}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:options:range:capture:error:}{- componentsMatchedByRegex:options:range:capture:error:}] Returns a \Code{NSArray} containing all the substrings from the receiver that were matched by the regular expression \Argument{regex} within \Argument{range} using \Argument{options}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:}{- enumerateStringsMatchedByRegex:usingBlock:}] Enumerates the matches in the receiver by the regular expression \Argument{regex} and executes \Argument{block} for each match found.
  \item[\parbox{\textwidth}{\RaggedRight{}\RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:options:inRange:error:enumerationOptions:usingBlock:}{- enumerateStringsMatchedByRegex:options:inRange:error:\\~~enumerationOptions:usingBlock:}}] Enumerates the matches in the receiver by the regular expression \Argument{regex} within \Argument{range} using \Argument{options} and executes \Argument{block} using \Argument{enumerationOptions} for each match found.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Dividing Strings}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{- componentsSeparatedByRegex:}] Returns a \Code{NSArray} containing substrings of the receiver that have been divided by the regular expression \Argument{regex}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:range:}{- componentsSeparatedByRegex:range:}] Returns a \Code{NSArray} containing substrings within range of the receiver that have been divided by the regular expression \Argument{regex}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:options:range:error:}{- componentsSeparatedByRegex:options:range:error:}] Returns a \Code{NSArray} containing substrings within range of the receiver that have been divided by the regular expression \Argument{regex} using \Argument{options}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:usingBlock:}{- enumerateStringsSeparatedByRegex:usingBlock:}] Enumerates the strings of the receiver that have been divided by the regular expression \Argument{regex} and executes \Argument{block} for each divided string.
  \item[\parbox{\textwidth}{\RaggedRight{}\RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:options:inRange:error:enumerationOptions:usingBlock:}{- enumerateStringsSeparatedByRegex:options:inRange:error:\\~~enumerationOptions:usingBlock:}}] Enumerates the strings of the receiver that have been divided by the regular expression \Argument{regex} within \Argument{range} using \Argument{options} and executes \Argument{block} using \Argument{enumerationOptions} for each divided string.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Identifying Matches}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-isMatchedByRegex:}{- isMatchedByRegex:}] Returns a Boolean value that indicates whether the receiver is matched by \Argument{regex}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-isMatchedByRegex:inRange:}{- isMatchedByRegex:inRange:}] Returns a Boolean value that indicates whether the receiver is matched by \Argument{regex} within \Argument{range}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-isMatchedByRegex:options:inRange:error:}{- isMatchedByRegex:options:inRange:error:}] Returns a Boolean value that indicates whether the receiver is matched by \Argument{regex} within \Argument{range}.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Determining if a Regular Expression is Valid}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-isRegexValid}{- isRegexValid}] Returns a Boolean value that indicates whether the regular expression contained in the receiver is valid.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-isRegexValidWithOptions:error:}{- isRegexValidWithOptions:error:}] Returns a Boolean value that indicates whether the regular expression contained in the receiver is valid using \Argument{options}.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Determining the Range of a Match}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:}{- rangeOfRegex:}] Returns the range for the first match of \Argument{regex} in the receiver.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:capture:}{- rangeOfRegex:capture:}] Returns the range of capture number \Argument{capture} for the first match of \Argument{regex} in the receiver.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:inRange:}{- rangeOfRegex:inRange:}] Returns the range for the first match of \Argument{regex} within \Argument{range} of the receiver.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:}{- rangeOfRegex:options:inRange:capture:error:}] Returns the range of capture number \Argument{capture} for the first match of \Argument{regex} within \Argument{range} of the receiver.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Modifying Mutable Strings}
  \item[\RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:}{- replaceOccurrencesOfRegex:withString:}] Replaces all occurrences of the regular expression \Argument{regex} with the contents of replacement string after performing capture group substitutions, returning the number of replacements made.
  \item[\RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:range:}{- replaceOccurrencesOfRegex:withString:range:}] Replaces all occurrences of the regular expression \Argument{regex} within \Argument{range} with the contents of replacement string after performing capture group substitutions, returning the number of replacements made.
  \item[\RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:options:range:error:}{- replaceOccurrencesOfRegex:withString:options:range:error:}] Replaces all occurrences of the regular expression \Argument{regex} using \Argument{options} within \Argument{range} with the contents of replacement string after performing capture group substitutions, returning the number of replacements made.
  \item[\RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:}{- replaceOccurrencesOfRegex:usingBlock:}] Enumerates the matches in the receiver by the regular expression \Argument{regex} and executes \Argument{block} for each match found. Replaces the characters that were matched with the contents of the string returned by \Argument{block}, returning the number of replacements made.
  \item[\RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:}{- replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:}] Enumerates the matches in the receiver by the regular expression \Argument{regex} within \Argument{range} using \Argument{options} and executes \Argument{block} using \Argument{enumerationOptions} for each match found. Replaces the characters that were matched with the contents of the string returned by \Argument{block}, returning the number of replacements made.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Creating Temporary Strings from a Match}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:}{- stringByMatching:}] Returns a string created from the characters of the receiver that are in the range of the first match of \Argument{regex}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:capture:}{- stringByMatching:capture:}] Returns a string created from the characters of the receiver that are in the range of the first match of \Argument{regex} for \Argument{capture}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:inRange:}{- stringByMatching:inRange:}] Returns a string created from the characters of the receiver that are in the range of the first match of \Argument{regex} within \Argument{range} of the receiver.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:options:inRange:capture:error:}{- stringByMatching:options:inRange:capture:error:}] Returns a string created from the characters of the receiver that are in the range of the first match of \Argument{regex} using \Argument{options} within \Argument{range} of the receiver for \Argument{capture}.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Replacing Substrings}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:}{- stringByReplacingOccurrencesOfRegex:withString:}] Returns a string created from the characters of the receiver in which all matches of the regular expression \Argument{regex} are replaced with the contents of the replacement string after performing capture group substitutions.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:range:}{- stringByReplacingOccurrencesOfRegex:withString:range:}] Returns a string created from the characters within \Argument{range} of the receiver in which all matches of the regular expression \Argument{regex} are replaced with the contents of the replacement string after performing capture group substitutions.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:options:range:error:}{- stringByReplacingOccurrencesOfRegex:withString:options:range:error:}] Returns a string created from the characters within \Argument{range} of the receiver in which all matches of the regular expression \Argument{regex} using \Argument{options} are replaced with the contents of the replacement string after performing capture group substitutions.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:}{- stringByReplacingOccurrencesOfRegex:usingBlock:}] Enumerates the matches in the receiver by the regular expression \Argument{regex} and executes \Argument{block} for each match found. Returns a string created by replacing the characters that were matched in the receiver with the contents of the string returned by \Argument{block}.
  \item[\parbox{\textwidth}{\RaggedRight{}\RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:}{- stringByReplacingOccurrencesOfRegex:options:inRange:error:\\~~enumerationOptions:usingBlock:}}] Enumerates the matches in the receiver by the regular expression \Argument{regex} within \Argument{range} using \Argument{options} and executes \Argument{block} using \Argument{enumerationOptions} for each match found. Returns a string created by replacing the characters that were matched in the receiver with the contents of the string returned by \Argument{block}.
\end{RKLTaskSection}


\begin{RKLTaskSection}{Creating a Dictionary from a Match}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:withKeysAndCaptures:}{- dictionaryByMatchingRegex:withKeysAndCaptures:}] Creates and returns a dictionary containing the matches constructed from the specified set of \Argument{keys} and \Argument{captures} for the first match of \Argument{regex} in the receiver.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:range:withKeysAndCaptures:}{- dictionaryByMatchingRegex:range:withKeysAndCaptures:}] Creates and returns a dictionary containing the matches constructed from the specified set of \Argument{keys} and \Argument{captures} for the first match of \Argument{regex} within \Argument{range} of the receiver.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:}{- dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:}] Creates and returns a dictionary containing the matches constructed from the specified set of \Argument{keys} and \Argument{captures} for the first match of \Argument{regex} within \Argument{range} of the receiver using \Argument{options}.
\end{RKLTaskSection}

\begin{RKLTaskSection}{Creating a Dictionary for every Match}
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:}{- arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:}] Returns an array containing all the matches in the receiver that were matched by the regular expression \Argument{regex}. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:}{- arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:}] Returns an array containing all the matches in the receiver that were matched by the regular expression \Argument{regex} within \Argument{range}. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.
  \item[\RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:}{- arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:}] Returns an array containing all the matches in the receiver that were matched by the regular expression \Argument{regex} within \Argument{range} using \Argument{options}. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.
\end{RKLTaskSection}


\end{RKLTasks}


\begin{RKLMethods}
%\begin{RKLMethodsCodeFooter}

\section{DTrace Probe Points}


\LabeledMethodSelector{DTrace_RegexKitLiteProbePoints__compiledRegexCache}{RegexKitLite:::compiledRegexCache}

This probe point fires each time the compiled regular expression cache is accessed.

\SIGNATURE{\Bd{RegexKitLite:::compiledRegexCache}(unsigned long \Argument{eventID}, const char *\Argument{regexUTF8},\\~~~~int \Argument{options}, int \Argument{captures}, int \Argument{hitMiss}, int \Argument{icuStatusCode},\\~~~~const char *\Argument{icuErrorMessage}, double *\Argument{hitRate});}

\begin{RKLParameters}
  \item[\Code{arg0}, eventID] The unique ID for this mutex lock acquisition.
  \item[\Code{arg1}, regexUTF8] {\RaggedRight{}Up to 64 characters of the regular expression encoded in \UTF{8}. Must be copied with \linebreak \Code{copyinstr(arg1)}.}
  \item[\Code{arg2}, options] The \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} options used.
  \item[\Code{arg3}, captures] The number of captures present in the regular expression, or \Code{-1} if there was an error.
  \item[\Code{arg4}, hitMiss] A boolean value that indicates whether or not this event was a cache hit or not, or \Code{-1} if there was an error.
  \item[\Code{arg5}, icuStatusCode] If an error occurs, this contains the error number returned by ICU.
  \item[\Code{arg6}, icuErrorMessage] If an error occurs, this contains a \UTF{8} encoded string of the ICU error. Must be copied with \Code{copyinstr(arg6)}.
  \item[\Code{arg7}, hitRate] A pointer to a floating point value, between \Code{0.0} and \Code{100.0}, that represents the effectiveness of cache. Higher is better. Must be copied with \Code{copyin(arg7, sizeof(double))}.
\end{RKLParameters}

\begin{RKLDiscussionEnv}
An example of how to copy the \Code{double} value pointed to by \Argument{hitRate}:

\begin{lstlisting}
RegexKitLite*:::compiledRegexCache {
  this->hitRate = (double *)copyin(arg7, sizeof(double));
  printf("compiledRegexCache hitRate: %6.2f%%\n", this->hitRate);
}
\end{lstlisting}
\end{RKLDiscussionEnv}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{DTrace_RegexKitLiteProbePoints__utf16ConversionCache}{RegexKitLite:::utf16ConversionCache}
  \item \RKLSectionPageRef{UsingRegexKitLite_DTrace}{Using \RegexKitLite{} - DTrace}
  \item \RKLSectionHref{http://docs.sun.com/app/docs/doc/817-6223}{Solaris Dynamic Tracing Guide} \RKLSectionHref{http://dlc.sun.com/pdf/817-6223/817-6223.pdf}{(as .PDF)}
\end{RKLSeeAlso}

%\end{RKLMethods}
%\begin{RKLMethodsCodeFooter}


\LabeledMethodSelector{DTrace_RegexKitLiteProbePoints__utf16ConversionCache}{RegexKitLite:::utf16ConversionCache}

This probe point fires each time the \UTF{16} conversion cache is accessed.

\SIGNATURE{\Bd{RegexKitLite:::utf16ConversionCache}(unsigned long \Argument{eventID},\\~~~~unsigned int \Argument{lookupResultFlags}, double *\Argument{hitRate}, const void *\Argument{string},\\~~~~unsigned long \Argument{NSRange\_location}, unsigned long \Argument{NSRange\_length}, long \Argument{length});}

\begin{RKLParameters}
  \item[\Code{arg0}, eventID] The unique ID for this mutex lock acquisition.
  \item[\Code{arg1}, lookupResultFlags] A set of status flags about the result of the conversion cache lookup.
  \item[\Code{arg2}, hitRate] A pointer to a floating point value, between \Code{0.0} and \Code{100.0}, that represents the effectiveness of cache. Higher is better. Must be copied with \Code{copyin(arg2, sizeof(double))}.
  \item[\Code{arg3}, string] A pointer to the \Code{NSString} that this \UTF{16} conversion cache check is being performed on.
  \item[\Code{arg4}, NSRange\_location] The location value of the \Argument{range} argument from the invoking \RegexKitLite{} method.
  \item[\Code{arg5}, NSRange\_length] The length value of the \Argument{range} argument from the invoking \RegexKitLite{} method.
  \item[\Code{arg6}, length] The length of the string.
\end{RKLParameters}

\begin{RKLDiscussionEnv}
Only strings that require a \UTF{16} conversion count towards the value calculated for \Argument{hitRate}.

An example of how to copy the \Code{double} value pointed to by \Argument{hitRate}:

\begin{lstlisting}
RegexKitLite*:::utf16ConversionCache {
  this->hitRate = (double *)copyin(arg2, sizeof(double));
  printf("utf16ConversionCache hitRate: %6.2f%%\n", this->hitRate);
}
\end{lstlisting}
\end{RKLDiscussionEnv}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{DTrace_RegexKitLiteProbePoints__compiledRegexCache}{RegexKitLite:::compiledRegexCache}
  \item \RKLSectionPageRef{dtrace_utf16ConversionCache_lookupResultFlags}{RegexKitLite:::utf16ConversionCache arg1 Flags}
  \item \RKLSectionPageRef{UsingRegexKitLite_DTrace}{Using \RegexKitLite{} - DTrace}
  \item \RKLSectionHref{http://docs.sun.com/app/docs/doc/817-6223}{Solaris Dynamic Tracing Guide} \RKLSectionHref{http://dlc.sun.com/pdf/817-6223/817-6223.pdf}{(as .PDF)}
\end{RKLSeeAlso}

%\end{RKLMethodsCodeFooter}
%\begin{RKLMethods}


\section{Class Methods}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__.captureCountForRegex:}{captureCountForRegex:}

{\RaggedRight{}Returns the number of captures that \Argument{regex} contains. \Deprecated{Deprecated in \RegexKitLite{ 3.0.}}  Use \linebreak{} \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCount}{captureCount} instead.}

\SIGNATURE{+ (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Selector{captureCountForRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}
\begin{RKLDiscussionEnv}
Since the capture count of a regular expression does not depend on the string to be searched, this is a \Code{NSString} class method.  For example:

\begin{lstlisting}
NSInteger regexCaptureCount = [NSString captureCountForRegex:@"(\\d+)\.(\\d+)"];
// regexCaptureCount would be set to 2.
\end{lstlisting}
\end{RKLDiscussionEnv}

\RKLAvailability{Deprecated in \RegexKitLite{ 3.0.}}

\RKLReturnValue{Returns \Code{-1} if an error occurs.  Otherwise the number of captures in \Argument{regex} is returned, or \Code{0} if \Argument{regex} does not contain any captures.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__.captureCountForRegex:options:error:}{+ captureCountForRegex:options:error:} \Deprecated{Deprecated in \RegexKitLite{ 3.0}}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCount}{- captureCount}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:}{- captureCountWithOptions:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__.captureCountForRegex:options:error:}{captureCountForRegex:options:error:}

{\RaggedRight{}Returns the number of captures that \Argument{regex} contains. \Deprecated{Deprecated in \RegexKitLite{ 3.0.}}  Use \linebreak \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:}{captureCountWithOptions:error:} instead.}

\SIGNATURE{+ (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Selector{captureCountForRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options}\\~~~~\Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\begin{RKLDiscussionEnv}
The optional \Argument{error} parameter, if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.

Since the capture count of a regular expression does not depend on the string to be searched, this is a \Code{NSString} class method.  For example:

\begin{lstlisting}
NSInteger regexCaptureCount = [NSString captureCountForRegex:@"(\\d+)\.(\\d+)"
                                                     options:RKLNoOptions
                                                       error:NULL];
// regexCaptureCount would be set to 2.
\end{lstlisting}
\end{RKLDiscussionEnv}

\RKLAvailability{Deprecated in \RegexKitLite{ 3.0.}}

\RKLReturnValue{Returns \Code{-1} if an error occurs.  Otherwise the number of captures in \Argument{regex} is returned, or \Code{0} if \Argument{regex} does not contain any captures.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__.captureCountForRegex:}{+ captureCountForRegex:} \Deprecated{Deprecated in \RegexKitLite{ 3.0}}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCount}{- captureCount}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:}{- captureCountWithOptions:error:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}

%\end{RKLMethods}
%\begin{RKLMethodsCodeFooter}
%\markright{\Code{clearStringCache}}
\LabeledMethodSelector{NSString_RegexKitLiteAdditions__.clearStringCache}{clearStringCache}

Clears the cached information about strings and cached compiled regular expressions.

\SIGNATURE{+ (void)\Selector{clearStringCache};}

\begin{RKLDiscussionEnv}
This method clears all the the cached state maintained by \RegexKitLite{.}  This includes all the cached compiled regular expressions and any cached \UTF{16} conversions.

An example of clearing the cache:

\begin{lstlisting}
[NSString clearStringCache]; // Clears all RegexKitLite cache state.
\end{lstlisting}

\RKLBoxWarning{When searching \Code{NSMutableString} objects that have mutated between searches, failure to clear the cache may result in undefined behavior.  Use \RKLCodePageRef{NSString_RegexKitLiteAdditions__-flushCachedRegexData}{flushCachedRegexData} to selectively clear the cached information about a \Code{NSMutableString} object.}

\RKLBoxNote{You do not need to call \RKLCodePageRef{NSString_RegexKitLiteAdditions__.clearStringCache}{clearStringCache} or \RKLCodePageRef{NSString_RegexKitLiteAdditions__-flushCachedRegexData}{flushCachedRegexData} when using the \Code{NSMutableString} \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:}{replaceOccurrencesOfRegex:withString:} methods. The cache entry for that regular expression and \Code{NSMutableString} is automatically cleared as necessary.}
  
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 1.1} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-flushCachedRegexData}{- flushCachedRegexData}
  \item \RKLSectionPageRef{NSString_RegexKitLiteAdditions__CachedInformationandMutableStrings}{NSString \RegexKitLite{} Additions Reference - Cached Information and Mutable Strings}
\end{RKLSeeAlso}


\section{Instance Methods}

\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:}{arrayOfCaptureComponentsMatchedByRegex:}

Returns an array containing all the matches from the receiver that were matched by the regular expression \Argument{regex}. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{arrayOfCaptureComponentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

\RKLReturnValue{A \Code{NSArray} object containing all the matches from the receiver by \Argument{regex}. Each match result consists of a \Code{NSArray} which contains all the capture groups present in \Argument{regex}.  Array index \Code{0} represents all of the text matched by \Argument{regex} and subsequent array indexes contain the text matched by their respective capture group.}

\RKLDiscussion{A match result array index will contain an empty string, or \Code{@""}, if a capture group did not match any text.}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:range:}{- arrayOfCaptureComponentsMatchedByRegex:range:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:options:range:error:}{- arrayOfCaptureComponentsMatchedByRegex:options:range:error:}
\end{RKLSeeAlso}

\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:range:}{arrayOfCaptureComponentsMatchedByRegex:range:}

Returns an array containing all the matches from the receiver that were matched by the regular expression \Argument{regex} within \Argument{range}. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{arrayOfCaptureComponentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range};}
  
\RKLReturnValue{A \Code{NSArray} object containing all the matches from the receiver by \Argument{regex}. Each match result consists of a \Code{NSArray} which contains all the capture groups present in \Argument{regex}.  Array index \Code{0} represents all of the text matched by \Argument{regex} and subsequent array indexes contain the text matched by their respective capture group.}

\RKLDiscussion{A match result array index will contain an empty string, or \Code{@""}, if a capture group did not match any text.}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:}{- arrayOfCaptureComponentsMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:options:range:error:}{- arrayOfCaptureComponentsMatchedByRegex:options:range:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:options:range:error:}{arrayOfCaptureComponentsMatchedByRegex:options:range:error:}

Returns an array containing all the matches from the receiver that were matched by the regular expression \Argument{regex} within \Argument{range} using \Argument{options}. Each match result consists of an array of the substrings matched by all the capture groups present in the regular expression.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{arrayOfCaptureComponentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
\end{RKLParameters}

\RKLReturnValue{A \Code{NSArray} object containing all the matches from the receiver by \Argument{regex}. Each match result consists of a \Code{NSArray} which contains all the capture groups present in \Argument{regex}.  Array index \Code{0} represents all of the text matched by \Argument{regex} and subsequent array indexes contain the text matched by their respective capture group.}

\begin{RKLDiscussionEnv}
If the receiver is not matched by \Argument{regex} then the returned value is a \Code{NSArray} that contains no items.

A match result array index will contain an empty string, or \Code{@""}, if a capture group did not match any text.

The match results in the array appear in the order they did in the receiver. For example, this code fragment:

\begin{lstlisting}
NSString *list      = @"$10.23, $1024.42, $3099";
NSString *regex     = @"\\$((\\d+)(?:\\.(\\d+)|\\.?))";
NSArray  *listItems = [list arrayOfCaptureComponentsMatchedByRegex:regex];
\end{lstlisting}

produces a \Code{NSArray} equivalent to:

\begin{lstlisting}
[NSArray arrayWithObjects:
    [NSArray arrayWithObjects:  @"$10.23",   @"10.23",   @"10", @"23", NULL], // Idx 0
    [NSArray arrayWithObjects:@"$1024.42", @"1024.42", @"1024", @"42", NULL], // Idx 1
    [NSArray arrayWithObjects:   @"$3099",    @"3099", @"3099",   @"", NULL], // Idx 2
    NULL];
\end{lstlisting}
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:}{- arrayOfCaptureComponentsMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:range:}{- arrayOfCaptureComponentsMatchedByRegex:range:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}

%\end{RKLMethods}
%\begin{RKLMethodsCodeFooter}






\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:}{arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:}

Returns an array containing all the matches in the receiver that were matched by the regular expression \Argument{regex}. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{arrayOfDictionariesByMatchingRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{withKeysAndCaptures:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/id}{id})\Argument{firstKey}, \Argument{...};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[firstKey] The first key to add to the new dictionary.
  \item[...] First the \Argument{capture} for \Argument{firstKey}, then a \Code{NULL}-terminated list of alternating \Argument{keys} and \Argument{captures}. \DLBrk{} \Argument{Captures} are specified using \Code{int} values.
    \RKLBoxImportant{Use of non-\Code{int} sized \Argument{capture} arguments will result in undefined behavior.  \Bd{Do not} append \Argument{capture} arguments with a \Code{L} suffix.}
    \RKLBoxImportant{Failure to \Code{NULL}-terminate the \Argument{keys} and \Argument{captures} list will result in undefined behavior.}
\end{RKLParameters}

\RKLReturnValue{A \Code{NSArray} object containing all the matches from the receiver by \Argument{regex}. Each match result consists of a \Code{NSDictionary} containing that matches substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.}

\begin{RKLDiscussionEnv}
If the receiver is not matched by \Argument{regex} then the returned value is a \Code{NSArray} that contains no items.

A dictionary will not contain a given key if its corresponding capture group did not match any text.
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:}{- arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:}{- arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:}{arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:}

Returns an array containing all the matches in the receiver that were matched by the regular expression \Argument{regex} within \Argument{range}. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{arrayOfDictionariesByMatchingRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range}\\~~~~\Selector{withKeysAndCaptures:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/id}{id})\Argument{firstKey}, \Argument{...};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[range] The range of the receiver to search.
  \item[firstKey] The first key to add to the new dictionary.
  \item[...] First the \Argument{capture} for \Argument{firstKey}, then a \Code{NULL}-terminated list of alternating \Argument{keys} and \Argument{captures}. \DLBrk{} \Argument{Captures} are specified using \Code{int} values.
    \RKLBoxImportant{Use of non-\Code{int} sized \Argument{capture} arguments will result in undefined behavior.  \Bd{Do not} append \Argument{capture} arguments with a \Code{L} suffix.}
    \RKLBoxImportant{Failure to \Code{NULL}-terminate the \Argument{keys} and \Argument{captures} list will result in undefined behavior.}
\end{RKLParameters}

\RKLReturnValue{A \Code{NSArray} object containing all the matches from the receiver by \Argument{regex}. Each match result consists of a \Code{NSDictionary} containing that matches substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.}

\begin{RKLDiscussionEnv}
If the receiver is not matched by \Argument{regex} then the returned value is a \Code{NSArray} that contains no items.

A dictionary will not contain a given key if its corresponding capture group did not match any text.
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:}{- arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:}{- arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}

\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:}{\protect\texorpdfstring{arrayOfDictionariesByMatchingRegex:options:range:error:\protect\linebreak{}withKeysAndCaptures:}{arrayOfDictionariesByMatchingRegex:options:range:error:withKeysAndCaptures:}}

Returns an array containing all the matches in the receiver that were matched by the regular expression \Argument{regex} within \Argument{range} using \Argument{options}. Each match result consists of a dictionary containing that matches substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.


\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{arrayOfDictionariesByMatchingRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error}\\~~~~\Selector{withKeysAndCaptures:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/id}{id})\Argument{firstKey}, \Argument{...};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
  \item[firstKey] The first key to add to the new dictionary.
  \item[...] First the \Argument{capture} for \Argument{firstKey}, then a \Code{NULL}-terminated list of alternating \Argument{keys} and \Argument{captures}. \DLBrk{} \Argument{Captures} are specified using \Code{int} values.
    \RKLBoxImportant{Use of non-\Code{int} sized \Argument{capture} arguments will result in undefined behavior.  \Bd{Do not} append \Argument{capture} arguments with a \Code{L} suffix.}
    \RKLBoxImportant{Failure to \Code{NULL}-terminate the \Argument{keys} and \Argument{captures} list will result in undefined behavior.}
\end{RKLParameters}

\RKLReturnValue{A \Code{NSArray} object containing all the matches from the receiver by \Argument{regex}. Each match result consists of a \Code{NSDictionary} containing that matches substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.}

\begin{RKLDiscussionEnv}
If the receiver is not matched by \Argument{regex} then the returned value is a \Code{NSArray} that contains no items.

A dictionary will not contain a given key if its corresponding capture group did not match any text.  It is important to note that a regular expression can successfully match zero characters:

\begin{lstlisting}
    NSString *name      = @"Name: Bob\n"
                          @"Name: John Smith";
    NSString *regex     = @"(?m)^Name:\\s*(\\w*)\\s*(\\w*)$";
    NSArray  *nameArray = 
    [name arrayOfDictionariesByMatchingRegex:regex
                                     options:RKLNoOptions
                                       range:NSMakeRange(0UL, [name length])
                                       error:NULL
                         withKeysAndCaptures:@"first", 1, @"last", 2, NULL];

// 2010-04-16 01:15:30.061 RegexKitLite[42984:a0f] nameArray: (
//         { first = Bob,  last = ""    },
//         { first = John, last = Smith }
// )
\end{lstlisting}

Compared to this example, where the second capture group does not match any characters:

\begin{lstlisting}
    NSString *name      = @"Name: Bob\n"
                          @"Name: John Smith";
    NSString *regex     = @"(?m)^Name:\\s*(\\w*)(?:\\s*|\\s+(\\w+))$";
    NSArray  *nameArray = 
    [name arrayOfDictionariesByMatchingRegex:regex
                                     options:RKLNoOptions
                                       range:NSMakeRange(0UL, [name length])
                                       error:NULL
                         withKeysAndCaptures:@"first", 1, @"last", 2, NULL];

// 2010-04-16 01:15:30.061 RegexKitLite[42984:a0f] nameArray: (
//         { first = Bob                },
//         { first = John, last = Smith }
// )
\end{lstlisting}
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:}{- arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:}{- arrayOfDictionariesByMatchingRegex:range:withKeysAndCaptures:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}




\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:}{captureComponentsMatchedByRegex:}

Returns an array containing the substrings matched by each capture group present in \Argument{regex} for the first match of \Argument{regex} in the receiver.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{captureComponentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

\RKLReturnValue{A \Code{NSArray} containing the substrings matched by each capture group present in \Argument{regex} for the first match of \Argument{regex} in the receiver. Array index \Code{0} represents all of the text matched by \Argument{regex} and subsequent array indexes contain the text matched by their respective capture group.}

\RKLDiscussion{A match result array index will contain an empty string, or \Code{@""}, if a capture group did not match any text.}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:range:}{- captureComponentsMatchedByRegex:range:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:options:range:error:}{- captureComponentsMatchedByRegex:options:range:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:range:}{captureComponentsMatchedByRegex:range:}

Returns an array containing the substrings matched by each capture group present in \Argument{regex} for the first match of \Argument{regex} within \Argument{range} of the receiver.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{captureComponentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range};}

\RKLReturnValue{A \Code{NSArray} containing the substrings matched by each capture group present in \Argument{regex} for the first match of \Argument{regex} within \Argument{range} of the receiver. Array index \Code{0} represents all of the text matched by \Argument{regex} and subsequent array indexes contain the text matched by their respective capture group.}

\RKLDiscussion{A match result array index will contain an empty string, or \Code{@""}, if a capture group did not match any text.}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:}{- captureComponentsMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:options:range:error:}{- captureComponentsMatchedByRegex:options:range:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:options:range:error:}{captureComponentsMatchedByRegex:options:range:error:}

Returns an array containing the substrings matched by each capture group present in \Argument{regex} for the first match of \Argument{regex} within \Argument{range} of the receiver using \Argument{options}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{captureComponentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
\end{RKLParameters}

\RKLReturnValue{A \Code{NSArray} containing the substrings matched by each capture group present in \Argument{regex} for the first match of \Argument{regex} within \Argument{range} of the receiver using \Argument{options}. Array index \Code{0} represents all of the text matched by \Argument{regex} and subsequent array indexes contain the text matched by their respective capture group.}

\begin{RKLDiscussionEnv}
If the receiver is not matched by \Argument{regex} then the returned value is a \Code{NSArray} that contains no items.

A match result array index will contain an empty string, or \Code{@""}, if a capture group did not match any text.

The returned value is for the first match of \Argument{regex} in the receiver.  For example, this code fragment:

\begin{lstlisting}
NSString *list      = @"$10.23, $1024.42, $3099";
NSString *regex     = @"\\$((\\d+)(?:\\.(\\d+)|\\.?))";
NSArray  *listItems = [list captureComponentsMatchedByRegex:regex];
\end{lstlisting}

produces a \Code{NSArray} equivalent to:

\begin{lstlisting}
[NSArray arrayWithObjects: @"$10.23", @"10.23", @"10", @"23", NULL];
\end{lstlisting}
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:}{- captureComponentsMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:range:}{- captureComponentsMatchedByRegex:range:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-captureCount}{captureCount}

Returns the number of captures that \Argument{regex} contains.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Selector{captureCount};}

\begin{RKLDiscussionEnv}
Returns the capture count of the receiver, which should be a valid regular expression.  For example:

\begin{lstlisting}
NSInteger regexCaptureCount = [@"(\\d+)\.(\\d+)" captureCount];
// regexCaptureCount would be set to 2.
\end{lstlisting}
\end{RKLDiscussionEnv}

\RKLReturnValue{Returns \Code{-1} if an error occurs.  Otherwise the number of captures in \Argument{regex} is returned, or \Code{0} if \Argument{regex} does not contain any captures.}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:}{- captureCountWithOptions:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-captureCountWithOptions:error:}{captureCountWithOptions:error:}

Returns the number of captures that \Argument{regex} contains.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Selector{captureCountWithOptions:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\begin{RKLDiscussionEnv}
The optional \Argument{error} parameter, if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.

Returns the capture count of the receiver, which should be a valid regular expression.  For example:

\begin{lstlisting}
NSInteger regexCaptureCount = [@"(\\d+)\.(\\d+)" captureCountWithOptions:RKLNoOptions
                                                                   error:NULL];
// regexCaptureCount would be set to 2.
\end{lstlisting}
\end{RKLDiscussionEnv}

\RKLReturnValue{Returns \Code{-1} if an error occurs.  Otherwise the number of captures in \Argument{regex} is returned, or \Code{0} if \Argument{regex} does not contain any captures.}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCount}{- captureCount}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:}{componentsMatchedByRegex:}

Returns an array containing all the substrings from the receiver that were matched by the regular expression \Argument{regex}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{componentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

\RKLReturnValue{A \Code{NSArray} object containing all the substrings from the receiver that were matched by \Argument{regex}.}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:capture:}{- componentsMatchedByRegex:capture:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:range:}{- componentsMatchedByRegex:range:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:options:range:capture:error:}{- componentsMatchedByRegex:options:range:capture:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:capture:}{componentsMatchedByRegex:capture:}

Returns an array containing all the substrings from the receiver that were matched by capture number \linebreak \Argument{capture} from the regular expression \Argument{regex}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{componentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{capture:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Argument{capture};}
\RKLReturnValue{A \Code{NSArray} object containing all the substrings for capture group \Argument{capture} from the receiver that were matched by \Argument{regex}.}

\RKLDiscussion{An array index will contain an empty string, or \Code{@""}, if the capture group did not match any text.}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:}{- componentsMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:range:}{- componentsMatchedByRegex:range:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:options:range:capture:error:}{- componentsMatchedByRegex:options:range:capture:error:}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:range:}{componentsMatchedByRegex:range:}

Returns an array containing all the substrings from the receiver that were matched by the regular expression \Argument{regex} within \Argument{range}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{componentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range};}

\RKLReturnValue{A \Code{NSArray} object containing all the substrings from the receiver that were matched by \Argument{regex} within \Argument{range}.}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:}{- componentsMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:capture:}{- componentsMatchedByRegex:capture:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:options:range:capture:error:}{- componentsMatchedByRegex:options:range:capture:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:options:range:capture:error:}{componentsMatchedByRegex:options:range:capture:error:}

Returns an array containing all the substrings from the receiver that were matched by capture number \linebreak \Argument{capture} from the regular expression \Argument{regex} within \Argument{range} using \Argument{options}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{componentsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~ \Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{capture:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Argument{capture}\\~~~~ \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[capture] The string matched by \Argument{capture} from \Argument{regex} to return. Use \Code{0} for the entire string that \Argument{regex} matched.
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
\end{RKLParameters}

\RKLReturnValue{A \Code{NSArray} object containing all the substrings from the receiver that were matched by capture number \Argument{capture} from \Argument{regex} within \Argument{range} using \Argument{options}.}

\begin{RKLDiscussionEnv}
If the receiver is not matched by \Argument{regex} then the returned value is a \Code{NSArray} that contains no items.

An array index will contain an empty string, or \Code{@""}, if a capture group did not match any text.

The match results in the array appear in the order they did in the receiver.

Example:

\begin{lstlisting}
NSString *list      = @"$10.23, $1024.42, $3099";
NSArray  *listItems = [list componentsMatchedByRegex:@"\\$((\\d+)(?:\\.(\\d+)|\\.?))"];

// listItems == [NSArray arrayWithObjects:@"$10.23", @"$1024.42", @"$3099", NULL];
\end{lstlisting}

Example of extracting a specific capture group:

\begin{lstlisting}
NSString *list      = @"$10.23, $1024.42, $3099";
NSRange   listRange = NSMakeRange(0UL, [list length]);
NSArray  *listItems = [list componentsMatchedByRegex:@"\\$((\\d+)(?:\\.(\\d+)|\\.?))"
                                             options:RKLNoOptions
                                               range:listRange
                                             capture:3L
                                               error:NULL];

// listItems == [NSArray arrayWithObjects:@"23", @"42", @"", NULL];
\end{lstlisting}
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:}{- componentsMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:capture:}{- componentsMatchedByRegex:capture:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:range:}{- componentsMatchedByRegex:range:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{componentsSeparatedByRegex:}

Returns an array containing substrings from the receiver that have been divided by the regular expression \Argument{regex}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{componentsSeparatedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

\RKLReturnValue{A \Code{NSArray} object containing the substrings from the receiver that have been divided by \Argument{regex}.}

\RKLAvailability{Available in \RegexKitLite{ 2.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:range:}{- componentsSeparatedByRegex:range:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:options:range:error:}{- componentsSeparatedByRegex:options:range:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:range:}{componentsSeparatedByRegex:range:}

Returns an array containing substrings within \Argument{range} of the receiver that have been divided by the regular expression \Argument{regex}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{componentsSeparatedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range};}

\RKLReturnValue{A \Code{NSArray} object containing the substrings from the receiver that have been divided by \Argument{regex}.}

\RKLAvailability{Available in \RegexKitLite{ 2.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{- componentsSeparatedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:options:range:error:}{- componentsSeparatedByRegex:options:range:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:options:range:error:}{componentsSeparatedByRegex:options:range:error:}

Returns an array containing substrings within \Argument{range} of the receiver that have been divided by the regular expression \Argument{regex} using \Argument{options}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Selector{componentsSeparatedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
\end{RKLParameters}

\RKLReturnValue{A \Code{NSArray} object containing the substrings from the receiver that have been divided by \Argument{regex}.}

\begin{RKLDiscussionEnv}
The substrings in the array appear in the order they did in the receiver. For example, this code fragment:

\begin{lstlisting}
NSString *list      = @"Norman, Stanley, Fletcher";
NSArray  *listItems = [list componentsSeparatedByRegex:@",\\s*"];
\end{lstlisting}

produces an array \Code{\{ @"Norman", @"Stanley", @"Fletcher" \}}.

If the receiver begins or ends with \Argument{regex}, then the first or last substring is, respectively, empty.  For example, the string \Code{",~Norman,~Stanley,~Fletcher"} creates an array that has these contents: \Code{\{ @"", @"Norman", @"Stanley", @"Fletcher" \}}.

If the receiver has no separators that are matched by \Argument{regex}\textendash{} for example, \Code{"Norman"}\textendash{} the array contains the string itself, in this case \Code{\{ @"Norman" \}}.

If \Argument{regex} contains capture groups\textendash{} for example, \Code{@",(\textbackslash{}\textbackslash{}s*)"}\textendash{} the array will contain the text matched by each capture group as a separate element appended to the normal result.  An additional element will be created for each capture group.  If an individual capture group does not match any text the result in the array will be a zero length string\textendash{} \Code{@""}. As an example\textendash{} the regular expression \Code{@",(\textbackslash{}\textbackslash{}s*)"} would produce the array \Code{\{ @"Norman", @"~", @"Stanley", @"~", @"Fletcher" \}}.
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 2.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{- componentsSeparatedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:range:}{- componentsSeparatedByRegex:range:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}





\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:withKeysAndCaptures:}{dictionaryByMatchingRegex:withKeysAndCaptures:}

Creates and returns a dictionary containing the matches constructed from the specified set of \Argument{keys} and \Argument{captures} for the first match of \Argument{regex} in the receiver.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSDictionary\_Class/Reference/Reference.html}{NSDictionary} *)\Selector{dictionaryByMatchingRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{withKeysAndCaptures:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/id}{id})\Argument{firstKey}, \Argument{...};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[firstKey] The first key to add to the new dictionary.
  \item[...] First the \Argument{capture} for \Argument{firstKey}, then a \Code{NULL}-terminated list of alternating \Argument{keys} and \Argument{captures}. \DLBrk{} \Argument{Captures} are specified using \Code{int} values.
    \RKLBoxImportant{Use of non-\Code{int} sized \Argument{capture} arguments will result in undefined behavior.  \Bd{Do not} append \Argument{capture} arguments with a \Code{L} suffix.}
    \RKLBoxImportant{Failure to \Code{NULL}-terminate the \Argument{keys} and \Argument{captures} list will result in undefined behavior.}
\end{RKLParameters}

\RKLReturnValue{A \Code{NSDictionary} containing the matched substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.}

\begin{RKLDiscussionEnv}
The returned value is for the first match of \Argument{regex} in the receiver.

If the receiver is not matched by \Argument{regex} then the returned value is a \Code{NSDictionary} that contains no items.

A dictionary will not contain a given key if its corresponding capture group did not match any text.
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:range:withKeysAndCaptures:}{- dictionaryByMatchingRegex:range:withKeysAndCaptures:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:}{- dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}




\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:range:withKeysAndCaptures:}{dictionaryByMatchingRegex:range:withKeysAndCaptures:}

Creates and returns a dictionary containing the matches constructed from the specified set of \Argument{keys} and \Argument{captures} for the first match of \Argument{regex} within \Argument{range} of the receiver.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSDictionary\_Class/Reference/Reference.html}{NSDictionary} *)\Selector{dictionaryByMatchingRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range}\\~~~~\Selector{withKeysAndCaptures:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/id}{id})\Argument{firstKey}, \Argument{...};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[range] The range of the receiver to search.
  \item[firstKey] The first key to add to the new dictionary.
  \item[...] First the \Argument{capture} for \Argument{firstKey}, then a \Code{NULL}-terminated list of alternating \Argument{keys} and \Argument{captures}. \DLBrk{} \Argument{Captures} are specified using \Code{int} values.
    \RKLBoxImportant{Use of non-\Code{int} sized \Argument{capture} arguments will result in undefined behavior.  \Bd{Do not} append \Argument{capture} arguments with a \Code{L} suffix.}
    \RKLBoxImportant{Failure to \Code{NULL}-terminate the \Argument{keys} and \Argument{captures} list will result in undefined behavior.}
\end{RKLParameters}

\RKLReturnValue{A \Code{NSDictionary} containing the matched substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.}

\begin{RKLDiscussionEnv}
The returned value is for the first match of \Argument{regex} in the receiver.

If the receiver is not matched by \Argument{regex} then the returned value is a \Code{NSDictionary} that contains no items.

A dictionary will not contain a given key if its corresponding capture group did not match any text.
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:withKeysAndCaptures:}{- dictionaryByMatchingRegex:withKeysAndCaptures:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:}{- dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:}{dictionaryByMatchingRegex:options:range:error:withKeysAndCaptures:}

Creates and returns a dictionary containing the matches constructed from the specified set of \Argument{keys} and \Argument{captures} for the first match of \Argument{regex} within \Argument{range} of the receiver using \Argument{options}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSDictionary\_Class/Reference/Reference.html}{NSDictionary} *)\Selector{dictionaryByMatchingRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error}\\~~~~\Selector{withKeysAndCaptures:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/id}{id})\Argument{firstKey}, \Argument{...};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
  \item[firstKey] The first key to add to the new dictionary.
  \item[...] First the \Argument{capture} for \Argument{firstKey}, then a \Code{NULL}-terminated list of alternating \Argument{keys} and \Argument{captures}. \DLBrk{} \Argument{Captures} are specified using \Code{int} values.
    \RKLBoxImportant{Use of non-\Code{int} sized \Argument{capture} arguments will result in undefined behavior.  \Bd{Do not} append \Argument{capture} arguments with a \Code{L} suffix.}
    \RKLBoxImportant{Failure to \Code{NULL}-terminate the \Argument{keys} and \Argument{captures} list will result in undefined behavior.}
\end{RKLParameters}

\RKLReturnValue{A \Code{NSDictionary} containing the matched substrings constructed from the specified set of \Argument{keys} and \Argument{captures}.}

\begin{RKLDiscussionEnv}
The returned value is for the first match of \Argument{regex} in the receiver.

If the receiver is not matched by \Argument{regex} then the returned value is a \Code{NSDictionary} that contains no items.

A dictionary will not contain a given key if its corresponding capture group did not match any text.  It is important to note that a regular expression can successfully match zero characters:

\begin{lstlisting}
NSString     *name           = @"Name: Joe";
NSString     *regex          = @"Name:\\s*(\\w*)\\s*(\\w*)";
NSDictionary *nameDictionary = 
                  [name dictionaryByMatchingRegex:regex
                                          options:RKLNoOptions
                                            range:NSMakeRange(0UL, [name length])
                                            error:NULL
                              withKeysAndCaptures:@"first", 1, @"last", 2, NULL];

// 2010-01-29 12:19:54.559 RegexKitLite[64944:a0f] nameDictionary: {
//     first = Joe;
//     last = "";
// }
\end{lstlisting}

Compared to this example, where the second capture group does not match any characters:

\begin{lstlisting}[escapeinside=``]
NSString     *name           = @"Name: Joe";
NSString     *regex          = @"Name:\\s*(\\w*)\\s*(\\w`\RKLHighlightRect{\Code{+)?}}`";
NSDictionary *nameDictionary =
                  [name dictionaryByMatchingRegex:regex
                                          options:RKLNoOptions
                                            range:NSMakeRange(0UL, [name length])
                                            error:NULL
                              withKeysAndCaptures:@"first", 1, @"last", 2, NULL];

// 2010-01-29 12:12:52.177 RegexKitLite[64893:a0f] nameDictionary: {
//     first = Joe;
// }
\end{lstlisting}
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:withKeysAndCaptures:}{- dictionaryByMatchingRegex:withKeysAndCaptures:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:range:withKeysAndCaptures:}{- dictionaryByMatchingRegex:range:withKeysAndCaptures:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}







\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:}{enumerateStringsMatchedByRegex:usingBlock:}

Enumerates the matches in the receiver by the regular expression \Argument{regex} and executes \Argument{block} for each match found.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{enumerateStringsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{usingBlock:}(void (\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~~~~~~~~~~~~~~~~~~~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}

\begin{RKLParameters}
  \item[regex] A \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} containing a regular expression.
  \item[block] The block that is executed for each match of \Argument{regex} in the receiver.  The block takes four arguments:
  \begin{RKLParameters}
    \item[captureCount] The number of strings that \Argument{regex} captured.  \Argument{captureCount} is always at least \Code{1}.
    \item[capturedStrings] An array containing the substrings matched by each capture group present in \Argument{regex}. The size of the array is \Argument{captureCount}. If a capture group did not match anything, it will contain a pointer to a string that is equal to \Code{@""}. This argument may be \Code{NULL} if \Argument{enumerationOptions} had \RKLCodePageRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired} set.
    \item[capturedRanges] An array containing the ranges matched by each capture group present in \Argument{regex}.  The size of the array is \Argument{captureCount}.  If a capture group did not match anything, it will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} equal to \Code{\{\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/constant\_group/NSNotFound}{NSNotFound}, 0\}}.
    \item[stop] A reference to a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} value that the block can use to stop the enumeration by setting \linebreak \Code{*}\Argument{stop}\Code{ = \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/macro/YES}{YES};}, otherwise it should not touch \Code{*}\Argument{stop}.
  \end{RKLParameters}
\end{RKLParameters}

\RKLReturnValue{Returns \Code{YES} if there was no error, otherwise returns \Code{NO}.}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \parbox{0.9\textwidth}{\RaggedRight{}\RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:options:inRange:error:enumerationOptions:usingBlock:}{- enumerateStringsMatchedByRegex:options:inRange:error:\\~~enumerationOptions:usingBlock:}}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{\RegexKitLite{} NSString Additions Reference - Block-based Enumeration Methods}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:options:inRange:error:enumerationOptions:usingBlock:}{\protect\texorpdfstring{enumerateStringsMatchedByRegex:options:inRange:error:\protect\linebreak{}enumerationOptions:usingBlock:}{enumerateStringsMatchedByRegex:options:inRange:error:enumerationOptions:usingBlock:}}

Enumerates the matches in the receiver by the regular expression \Argument{regex} within \Argument{range} using \Argument{options} and executes \Argument{block} using \Argument{enumerationOptions} for each match found.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{enumerateStringsMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error}\\~~~~\Selector{enumerationOptions:}(\RKLCodeRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions})\Argument{enumerationOptions}\\~~~~\Selector{usingBlock:}(void (\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~~~~~~~~~~~~~~~~~~~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}

\begin{RKLParameters}
  \item[regex] A \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[error] An optional parameter that if set and an error occurs, will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
  \item[enumerationOptions] A mask of options specified by combining \RKLCodePageRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLRegexEnumerationNoOptions}{RKLRegexEnumerationNoOptions} may be used if no options are required.
  \item[block] The block that is executed for each match of \Argument{regex} in the receiver.  The block takes four arguments:
  \begin{RKLParameters}
    \item[captureCount] The number of strings that \Argument{regex} captured.  \Argument{captureCount} is always at least \Code{1}.
    \item[capturedStrings] An array containing the substrings matched by each capture group present in \Argument{regex}. The size of the array is \Argument{captureCount}. If a capture group did not match anything, it will contain a pointer to a string that is equal to \Code{@""}. This argument may be \Code{NULL} if \Argument{enumerationOptions} had \RKLCodePageRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired} set.
    \item[capturedRanges] An array containing the ranges matched by each capture group present in \Argument{regex}.  The size of the array is \Argument{captureCount}.  If a capture group did not match anything, it will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} equal to \Code{\{\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/constant\_group/NSNotFound}{NSNotFound}, 0\}}.
    \item[stop] A reference to a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} value that the block can use to stop the enumeration by setting \linebreak \Code{*}\Argument{stop}\Code{ = \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/macro/YES}{YES};}, otherwise it should not touch \Code{*}\Argument{stop}.
  \end{RKLParameters}
\end{RKLParameters}

\RKLReturnValue{Returns \Code{YES} if there was no error, otherwise returns \Code{NO} and indirectly returns a \Code{NSError} object if \Argument{error} is not \Code{NULL}.}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:}{- enumerateStringsMatchedByRegex:usingBlock:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
  \item \RKLSectionPageRef{RegularExpressionEnumerationOptions}{Regular Expression Enumeration Options}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{\RegexKitLite{} NSString Additions Reference - Block-based Enumeration Methods}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
\end{RKLSeeAlso}







\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:usingBlock:}{enumerateStringsSeparatedByRegex:usingBlock:}

Enumerates the strings of the receiver that have been divided by the regular expression \Argument{regex} and executes \Argument{block} for each divided string.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{enumerateStringsSeparatedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{usingBlock:}(void (\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~~~~~~~~~~~~~~~~~~~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}

\begin{RKLParameters}
  \item[regex] A \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} containing a regular expression.
  \item[block] The block that is executed for each match of \Argument{regex} in the receiver.  The block takes four arguments:
  \begin{RKLParameters}
    \item[captureCount] The number of strings that \Argument{regex} captured.  \Argument{captureCount} is always at least \Code{1}.
    \item[capturedStrings] An array containing the substrings matched by each capture group present in \Argument{regex}. The size of the array is \Argument{captureCount}. If a capture group did not match anything, it will contain a pointer to a string that is equal to \Code{@""}. This argument may be \Code{NULL} if \Argument{enumerationOptions} had \RKLCodePageRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired} set.
    \item[capturedRanges] An array containing the ranges matched by each capture group present in \Argument{regex}.  The size of the array is \Argument{captureCount}.  If a capture group did not match anything, it will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} equal to \Code{\{\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/constant\_group/NSNotFound}{NSNotFound}, 0\}}.
    \item[stop] A reference to a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} value that the block can use to stop the enumeration by setting \linebreak \Code{*}\Argument{stop}\Code{ = \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/macro/YES}{YES};}, otherwise it should not touch \Code{*}\Argument{stop}.
  \end{RKLParameters}
\end{RKLParameters}

\RKLReturnValue{Returns \Code{YES} if there was no error, otherwise returns \Code{NO}.}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \parbox{0.9\textwidth}{\RaggedRight{}\RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:options:inRange:error:enumerationOptions:usingBlock:}{- enumerateStringsSeparatedByRegex:options:inRange:error:\\~~enumerationOptions:usingBlock:}}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{- componentsSeparatedByRegex:}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{\RegexKitLite{} NSString Additions Reference - Block-based Enumeration Methods}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
\end{RKLSeeAlso}





\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:options:inRange:error:enumerationOptions:usingBlock:}{\protect\texorpdfstring{enumerateStringsSeparatedByRegex:options:inRange:error:\protect\linebreak{}enumerationOptions:usingBlock:}{enumerateStringsSeparatedByRegex:options:inRange:error:enumerationOptions:usingBlock:}}

Enumerates the strings of the receiver that have been divided by the regular expression \Argument{regex} within \Argument{range} using \Argument{options} and executes \Argument{block} using \Argument{enumerationOptions} for each divided string.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{enumerateStringsSeparatedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error}\\~~~~\Selector{enumerationOptions:}(\RKLCodeRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions})\Argument{enumerationOptions}\\~~~~\Selector{usingBlock:}(void (\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~~~~~~~~~~~~~~~~~~~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}

\begin{RKLParameters}
  \item[regex] A \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[error] An optional parameter that if set and an error occurs, will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
  \item[enumerationOptions] A mask of options specified by combining \RKLCodePageRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLRegexEnumerationNoOptions}{RKLRegexEnumerationNoOptions} may be used if no options are required.
  \item[block] The block that is executed for each match of \Argument{regex} in the receiver.  The block takes four arguments:
  \begin{RKLParameters}
    \item[captureCount] The number of strings that \Argument{regex} captured.  \Argument{captureCount} is always at least \Code{1}.
    \item[capturedStrings] An array containing the substrings matched by each capture group present in \Argument{regex}. The size of the array is \Argument{captureCount}. If a capture group did not match anything, it will contain a pointer to a string that is equal to \Code{@""}. This argument may be \Code{NULL} if \Argument{enumerationOptions} had \RKLCodePageRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired} set.
    \item[capturedRanges] An array containing the ranges matched by each capture group present in \Argument{regex}.  The size of the array is \Argument{captureCount}.  If a capture group did not match anything, it will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} equal to \Code{\{\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/constant\_group/NSNotFound}{NSNotFound}, 0\}}.
    \item[stop] A reference to a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} value that the block can use to stop the enumeration by setting \linebreak \Code{*}\Argument{stop}\Code{ = \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/macro/YES}{YES};}, otherwise it should not touch \Code{*}\Argument{stop}.
  \end{RKLParameters}
\end{RKLParameters}

\RKLReturnValue{Returns \Code{YES} if there was no error, otherwise returns \Code{NO} and indirectly returns a \Code{NSError} object if \Argument{error} is not \Code{NULL}.}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:usingBlock:}{- enumerateStringsSeparatedByRegex:usingBlock:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:options:range:error:}{- componentsSeparatedByRegex:options:range:error:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
  \item \RKLSectionPageRef{RegularExpressionEnumerationOptions}{Regular Expression Enumeration Options}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{\RegexKitLite{} NSString Additions Reference - Block-based Enumeration Methods}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-flushCachedRegexData}{flushCachedRegexData}

Clears any cached information about the receiver.

\SIGNATURE{- (void)\Selector{flushCachedRegexData};}
\begin{RKLDiscussionEnv}
This method should be used when performing searches on \Code{NSMutableString} objects and there is the possibility that the string has mutated in between calls to \RegexKitLite{}.

This method clears the cached information for the receiver \Bd{only}.  This is more selective than \linebreak \RKLCodePageRef{NSString_RegexKitLiteAdditions__.clearStringCache}{clearStringCache}, which clears all the cached information from \RegexKitLite{,} including all the cached compiled regular expressions.

\RegexKitLite{} automatically detects the vast majority of string mutations and clears any cached information for the mutated string.  To detect mutations, \RegexKitLite{} records a strings \Code{length} and \Code{hash} value at the point in time when it caches data for a string.  Cached data for a string is invalidated if either of these values change between calls to \RegexKitLite{.}  The problem case is when a string is mutated but the strings length remains the same \Bd{and} the hash value for the mutated string is identical to the hash value of the string before it was mutated.  This is known as a \It{hash collision}.  Since \RegexKitLite{} is unable to detect that a string has mutated when this happens, the programmer needs to explicitly inform \RegexKitLite{} that any cached data about the receiver needs to be cleared by sending \Code{flushCachedRegexData} to the mutated string.

While it is possible to have "perfect mutation detection", and therefore guarantee that only valid cached data is used, it has a significant performance penalty.  The first problem is that when caching information about a string, an immutable copy of that string needs to be made.  The second problem is that determining that two strings are not identical is usually very fast and cheap\textendash{} if their lengths are not the same, no further checks are required.  The most expensive case is when two strings are identical because it requires a character by character comparison of the entire string to guarantee that they are equal.  The most expensive case also happens to be the most common case, by far.  To make matters worst, Cocoa provides no public way to determine if an instance is a mutable \Code{NSMutableString} or an immutable \Code{NSString} object.  Therefore \RegexKitLite{} must assume the worst case that all strings are mutable and have potentially mutated between calls to \RegexKitLite{}.

\RegexKitLite{} is optimized for the common case which is when regular expression operations are performed on strings that are not mutating. The majority of mutations to a string can be quickly and cheaply detected by \RegexKitLite{} automatically. Since the programmer has the context of the string that is to be matched, and whether or not the string is being mutated, \RegexKitLite{} relies on the programmer to inform it whether or not the possibility exists that the string could have mutated in a way that is undetectable.

An example of clearing a strings cached information:

\begin{lstlisting}
NSMutableString *mutableSearchString; // Assumed to be valid.
NSString *foundString = [mutableSearchString stringByMatching:@"\\d+"]; // Searched..

[mutableSearchString replaceCharactersInRange:NSMakeRange(5UL, 10UL)
                                   withString:@"[replaced]"]; // Mutated..

[mutableSearchString flushCachedRegexData]; // Clear cached information
                                            // about mutableSearchString.
\end{lstlisting}

\RKLBoxWarning{Failure to clear the cached information for a \Code{NSMutableString} object that has mutated between searches may result in undefined behavior.}

\RKLBoxNote{You do not need to call \RKLCodePageRef{NSString_RegexKitLiteAdditions__.clearStringCache}{clearStringCache} or \RKLCodePageRef{NSString_RegexKitLiteAdditions__-flushCachedRegexData}{flushCachedRegexData} when using the \Code{NSMutableString} \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:}{replaceOccurrencesOfRegex:withString:} methods. The cached information for that \Code{NSMutableString} is automatically cleared as necessary.}
  
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__.clearStringCache}{+ clearStringCache}
  \item \RKLSectionPageRef{NSString_RegexKitLiteAdditions__CachedInformationandMutableStrings}{NSString \RegexKitLite{} Additions Reference - Cached Information and Mutable Strings}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-isMatchedByRegex:}{isMatchedByRegex:}

Returns a Boolean value that indicates whether the receiver is matched by \Argument{regex}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{isMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-isMatchedByRegex:inRange:}{- isMatchedByRegex:inRange:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-isMatchedByRegex:options:inRange:error:}{- isMatchedByRegex:options:inRange:error:}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-isMatchedByRegex:inRange:}{isMatchedByRegex:inRange:}

Returns a Boolean value that indicates whether the receiver is matched by \Argument{regex} within \Argument{range}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{isMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range};}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-isMatchedByRegex:}{- isMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-isMatchedByRegex:options:inRange:error:}{- isMatchedByRegex:options:inRange:error:}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-isMatchedByRegex:options:inRange:error:}{isMatchedByRegex:options:inRange:error:}

Returns a Boolean value that indicates whether the receiver is matched by \Argument{regex} within \Argument{range}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{isMatchedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options}\\~~~~\Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\RKLDiscussion{The optional \Argument{error} parameter, if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-isMatchedByRegex:}{- isMatchedByRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-isMatchedByRegex:inRange:}{- isMatchedByRegex:inRange:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-isRegexValid}{isRegexValid}

Returns a Boolean value that indicates whether the regular expression contained in the receiver is valid.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{isRegexValid};}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-isRegexValidWithOptions:error:}{- isRegexValidWithOptions:error:}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-isRegexValidWithOptions:error:}{isRegexValidWithOptions:error:}

Returns a Boolean value that indicates whether the regular expression contained in the receiver is valid using \Argument{options}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\Selector{isRegexValidWithOptions:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\begin{RKLParameters}
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
\end{RKLParameters}

\begin{RKLDiscussionEnv}
This method can be used to determine if a regular expression is valid.  For example:

\begin{lstlisting}
NSError  *error       = NULL;
NSString *regexString = @"[a-z"; // Missing the closing ]
if([regexString isRegexValidWithOptions:RKLNoOptions error:&error] == NO) {
  NSLog(@"The regular expression is invalid. Error: %@", error);
}
\end{lstlisting}
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 3.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-isRegexValid}{- isRegexValid}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}




\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-rangeOfRegex:}{rangeOfRegex:}

Returns the range for the first match of \Argument{regex} in the receiver.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Selector{rangeOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

\RKLReturnValue{A \Code{NSRange} structure giving the location and length of the first match of \Argument{regex} in the receiver. Returns \Code{\{}\RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSNotFound}{NSNotFound}\Code{, 0\}} if the receiver is not matched by \Argument{regex} or an error occurs.}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:capture:}{- rangeOfRegex:capture:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:inRange:}{- rangeOfRegex:inRange:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:}{- rangeOfRegex:options:inRange:capture:error:}
\end{RKLSeeAlso}

\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-rangeOfRegex:capture:}{rangeOfRegex:capture:}

Returns the range of capture number \Argument{capture} for the first match of \Argument{regex} in the receiver.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Selector{rangeOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{capture:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Argument{capture};}

\RKLReturnValue{A \Code{NSRange} structure giving the location and length of capture number \Argument{capture} for the first match of \Argument{regex} in the receiver. Returns \Code{\{}\RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSNotFound}{NSNotFound}\Code{, 0\}} if the receiver is not matched by \Argument{regex} or an error occurs.}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:}{- rangeOfRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:inRange:}{- rangeOfRegex:inRange:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:}{- rangeOfRegex:options:inRange:capture:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-rangeOfRegex:inRange:}{rangeOfRegex:inRange:}

Returns the range for the first match of \Argument{regex} within \Argument{range} of the receiver.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Selector{rangeOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range};}

\RKLReturnValue{A \Code{NSRange} structure giving the location and length of the first match of \Argument{regex} within \Argument{range} of the receiver. Returns \Code{\{}\RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSNotFound}{NSNotFound}\Code{, 0\}} if the receiver is not matched by \Argument{regex} within \Argument{range} or an error occurs.}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:}{- rangeOfRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:capture:}{- rangeOfRegex:capture:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:}{- rangeOfRegex:options:inRange:capture:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-rangeOfRegex:options:inRange:capture:error:}{rangeOfRegex:options:inRange:capture:error:}

Returns the range of capture number \Argument{capture} for the first match of \Argument{regex} within \Argument{range} of the receiver.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Selector{rangeOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options}\\~~~~\Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{capture:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Argument{capture} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}
 
\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[capture] The matching range of the capture number from \Argument{regex} to return. Use \Code{0} for the entire range that \Argument{regex} matched.
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
\end{RKLParameters}

\RKLReturnValue{A \Code{NSRange} structure giving the location and length of capture number \Argument{capture} for the first match of \Argument{regex} within \Argument{range} of the receiver. Returns \Code{\{}\RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSNotFound}{NSNotFound}\Code{, 0\}} if the receiver is not matched by \Argument{regex} within \Argument{range} or an error occurs.}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:}{- rangeOfRegex:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:capture:}{- rangeOfRegex:capture:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-rangeOfRegex:inRange:}{- rangeOfRegex:inRange:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}




\LabeledMethodSelector{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:}{replaceOccurrencesOfRegex:usingBlock:}

Enumerates the matches in the receiver by the regular expression \Argument{regex} and executes \Argument{block} for each match found. Replaces the characters that were matched with the contents of the string returned by \Argument{block}, returning the number of replacements made.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Selector{replaceOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{usingBlock:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *(\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}

\begin{RKLParameters}
  \item[regex] A \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} containing a regular expression.
  \item[block] The block that is executed for each match of \Argument{regex} in the receiver.  The block takes four arguments:
  \begin{RKLParameters}
    \item[captureCount] The number of strings that \Argument{regex} captured.  \Argument{captureCount} is always at least \Code{1}.
    \item[capturedStrings] An array containing the substrings matched by each capture group present in \Argument{regex}. The size of the array is \Argument{captureCount}. If a capture group did not match anything, it will contain a pointer to a string that is equal to \Code{@""}. This argument may be \Code{NULL} if \Argument{enumerationOptions} had \RKLCodePageRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired} set.
    \item[capturedRanges] An array containing the ranges matched by each capture group present in \Argument{regex}.  The size of the array is \Argument{captureCount}.  If a capture group did not match anything, it will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} equal to \Code{\{\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/constant\_group/NSNotFound}{NSNotFound}, 0\}}.
    \item[stop] A reference to a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} value that the block can use to stop the enumeration by setting \linebreak \Code{*}\Argument{stop}\Code{ = \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/macro/YES}{YES};} otherwise it should not touch \Code{*}\Argument{stop}.
  \end{RKLParameters}
\end{RKLParameters}

\RKLDiscussion{This method modifies the receivers contents. An exception will be raised if it is sent to an immutable object.}

\RKLReturnValue{Returns \Code{-1} if there was an error, otherwise returns the number of replacements performed.}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:}{- replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{\RegexKitLite{} NSString Additions Reference - Block-based Enumeration Methods}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:}{\protect\texorpdfstring{replaceOccurrencesOfRegex:options:inRange:error:\protect\linebreak{}enumerationOptions:usingBlock:}{replaceOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:}}

Enumerates the matches in the receiver by the regular expression \Argument{regex} within \Argument{range} using \Argument{options} and executes \Argument{block} using \Argument{enumerationOptions} for each match found. Replaces the characters that were matched with the contents of the string returned by \Argument{block}, returning the number of replacements made.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Selector{replaceOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error}\\~~~~\Selector{enumerationOptions:}(\RKLCodeRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions})\Argument{enumerationOptions}\\~~~~\Selector{usingBlock:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *(\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}

\begin{RKLParameters}
  \item[regex] A \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[error] An optional parameter that if set and an error occurs, will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
  \item[enumerationOptions] A mask of options specified by combining \RKLCodePageRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLRegexEnumerationNoOptions}{RKLRegexEnumerationNoOptions} may be used if no options are required.
  \item[block] The block that is executed for each match of \Argument{regex} in the receiver.  The block takes four arguments:
        
  \begin{RKLParameters}
    \item[captureCount] The number of strings that \Argument{regex} captured.  \Argument{captureCount} is always at least \Code{1}.
    \item[capturedStrings] An array containing the substrings matched by each capture group present in \Argument{regex}. The size of the array is \Argument{captureCount}. If a capture group did not match anything, it will contain a pointer to a string that is equal to \Code{@""}. This argument may be \Code{NULL} if \Argument{enumerationOptions} had \RKLCodePageRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired} set.
    \item[capturedRanges] An array containing the ranges matched by each capture group present in \Argument{regex}.  The size of the array is \Argument{captureCount}.  If a capture group did not match anything, it will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} equal to \Code{\{\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/constant\_group/NSNotFound}{NSNotFound}, 0\}}.
    \item[stop] A reference to a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} value that the block can use to stop the enumeration by setting \linebreak \Code{*}\Argument{stop}\Code{ = \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/macro/YES}{YES};} otherwise it should not touch \Code{*}\Argument{stop}.
  \end{RKLParameters}
\end{RKLParameters}

\RKLDiscussion{This method modifies the receivers contents.  An exception will be raised if it is sent to an immutable object.}

\RKLReturnValue{Returns \Code{-1} if there was an error and indirectly returns a \Code{NSError} object if \Argument{error} is not \Code{NULL}, otherwise returns the number of replacements performed.}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:}{- replaceOccurrencesOfRegex:usingBlock:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
  \item \RKLSectionPageRef{RegularExpressionEnumerationOptions}{Regular Expression Enumeration Options}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{\RegexKitLite{} NSString Additions Reference - Block-based Enumeration Methods}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:}{replaceOccurrencesOfRegex:withString:}

Replaces all occurrences of the regular expression \Argument{regex} with the contents of \Argument{replacement} string after performing capture group substitutions, returning the number of replacements made.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Selector{replaceOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{withString:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{replacement};}

\RKLBoxImportant{Raises \RKLCodePageRef{RKLICURegexException}{RKLICURegexException} if \Argument{replacement} contains \Regex{\$}\Argument{n} capture references where \Argument{n} is greater than the number of capture groups in the regular expression \Argument{regex}.}

\RKLDiscussion{This method modifies the receivers contents.  An exception will be raised if it is sent to an immutable object.}

\RKLReturnValue{Returns \Code{-1} if there was an error, otherwise returns the number of replacements performed.}

\RKLAvailability{Available in \RegexKitLite{ 2.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:range:}{- replaceOccurrencesOfRegex:withString:range:}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:options:range:error:}{- replaceOccurrencesOfRegex:withString:options:range:error:}
  \item \RKLSectionPageRef{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:range:}{replaceOccurrencesOfRegex:withString:range:}

Replaces all occurrences of the regular expression \Argument{regex} within \Argument{range} with the contents of \Argument{replacement} string after performing capture group substitutions, returning the number of replacements made.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Selector{replaceOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{withString:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{replacement} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range};}

\RKLBoxImportant{Raises \RKLCodePageRef{RKLICURegexException}{RKLICURegexException} if \Argument{replacement} contains \Regex{\$}\Argument{n} capture references where \Argument{n} is greater than the number of capture groups in the regular expression \Argument{regex}.}

\RKLDiscussion{This method modifies the receivers contents.  An exception will be raised if it is sent to an immutable object.}

\RKLReturnValue{Returns \Code{-1} if there was an error, otherwise returns the number of replacements performed.}

\RKLAvailability{Available in \RegexKitLite{ 2.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:}{- replaceOccurrencesOfRegex:withString:}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:options:range:error:}{- replaceOccurrencesOfRegex:withString:options:range:error:}
  \item \RKLSectionPageRef{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:options:range:error:}{replaceOccurrencesOfRegex:withString:options:range:error:}

Replaces all occurrences of the regular expression \Argument{regex} using \Argument{options} within \Argument{range} with the contents of \Argument{replacement} string after performing capture group substitutions, returning the number of replacements made.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Selector{replaceOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{withString:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{replacement}\\~~~~\Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[replacement] The string to use as the replacement text for matches by \Argument{regex}.  See \RKLSectionPageRef{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax} for more information.
    \RKLBoxImportant{Raises \RKLCodePageRef{RKLICURegexException}{RKLICURegexException} if \Argument{replacement} contains \Regex{\$}\Argument{n} capture references where \Argument{n} is greater than the number of capture groups in the regular expression \Argument{regex}.}
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
\end{RKLParameters}

\RKLDiscussion{This method modifies the receivers contents.  An exception will be raised if it is sent to an immutable object.}

\RKLReturnValue{Returns \Code{-1} if there was an error and indirectly returns a \Code{NSError} object if \Argument{error} is not \Code{NULL}, otherwise returns the number of replacements performed.}

\RKLAvailability{Available in \RegexKitLite{ 2.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:}{- replaceOccurrencesOfRegex:withString:}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:range:}{- replaceOccurrencesOfRegex:withString:range:}
  \item \RKLSectionPageRef{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}

\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-stringByMatching:}{stringByMatching:}

Returns a string created from the characters of the receiver that are in the range of the first match of \Argument{regex}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByMatching:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

\RKLReturnValue{A \Code{NSString} containing the substring of the receiver matched by \Argument{regex}.  Returns \Code{NULL} if the receiver is not matched by \Argument{regex} or an error occurs.}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:capture:}{- stringByMatching:capture:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:inRange:}{- stringByMatching:inRange:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:options:inRange:capture:error:}{- stringByMatching:options:inRange:capture:error:}
\end{RKLSeeAlso}


\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-stringByMatching:capture:}{stringByMatching:capture:}

Returns a string created from the characters of the receiver that are in the range of the first match of \Argument{regex} for \Argument{capture}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByMatching:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{capture:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Argument{capture};}

\RKLReturnValue{A \Code{NSString} containing the substring of the receiver matched by capture number \Argument{capture} of \Argument{regex}.  Returns \Code{NULL} if the receiver is not matched by \Argument{regex} or an error occurs.}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:}{- stringByMatching:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:inRange:}{- stringByMatching:inRange:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:options:inRange:capture:error:}{- stringByMatching:options:inRange:capture:error:}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-stringByMatching:inRange:}{stringByMatching:inRange:}

Returns a string created from the characters of the receiver that are in the range of the first match of \Argument{regex} within \Argument{range} of the receiver.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByMatching:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range};}

\RKLReturnValue{A \Code{NSString} containing the substring of the receiver matched by \Argument{regex} within \Argument{range} of the receiver.  Returns \Code{NULL} if the receiver is not matched by \Argument{regex} within \Argument{range} or an error occurs.}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:}{- stringByMatching:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:capture:}{- stringByMatching:capture:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:options:inRange:capture:error:}{- stringByMatching:options:inRange:capture:error:}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-stringByMatching:options:inRange:capture:error:}{stringByMatching:options:inRange:capture:error:}

Returns a string created from the characters of the receiver that are in the range of the first match of \Argument{regex} using \Argument{options} within \Argument{range} of the receiver for \Argument{capture}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByMatching:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex} \Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options}\\~~~~\Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{capture:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\Argument{capture} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[capture] The string matched by \Argument{capture} from \Argument{regex} to return. Use \Code{0} for the entire string that \Argument{regex} matched.
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
\end{RKLParameters}

\RKLReturnValue{A \Code{NSString} containing the substring of the receiver matched by capture number \Argument{capture} of \Argument{regex} within \Argument{range} of the receiver.  Returns \Code{NULL} if the receiver is not matched by \Argument{regex} within \Argument{range} or an error occurs.}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:}{- stringByMatching:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:capture:}{- stringByMatching:capture:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByMatching:inRange:}{- stringByMatching:inRange:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}





\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:}{stringByReplacingOccurrencesOfRegex:usingBlock:}

Enumerates the matches in the receiver by the regular expression \Argument{regex} and executes \Argument{block} for each match found. Returns a string created by replacing the characters that were matched in the receiver with the contents of the string returned by \Argument{block}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByReplacingOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{usingBlock:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *(\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}

\begin{RKLParameters}
  \item[regex] A \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} containing a regular expression.
  \item[block] The block that is executed for each match of \Argument{regex} in the receiver.  The block takes four arguments:
  \begin{RKLParameters}
    \item[captureCount] The number of strings that \Argument{regex} captured.  \Argument{captureCount} is always at least \Code{1}.
    \item[capturedStrings] An array containing the substrings matched by each capture group present in \Argument{regex}. The size of the array is \Argument{captureCount}. If a capture group did not match anything, it will contain a pointer to a string that is equal to \Code{@""}. This argument may be \Code{NULL} if \Argument{enumerationOptions} had \RKLCodePageRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired} set.
    \item[capturedRanges] An array containing the ranges matched by each capture group present in \Argument{regex}.  The size of the array is \Argument{captureCount}.  If a capture group did not match anything, it will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} equal to \Code{\{\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/constant\_group/NSNotFound}{NSNotFound}, 0\}}.
    \item[stop] A reference to a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} value that the block can use to stop the enumeration by setting \linebreak \Code{*}\Argument{stop}\Code{ = \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/macro/YES}{YES};} otherwise it should not touch \Code{*}\Argument{stop}.
  \end{RKLParameters}
\end{RKLParameters}

\RKLReturnValue{A \Code{NSString} created from the characters of the receiver in which all matches of the regular expression \Argument{regex} are replaced with the contents of the \Code{NSString} returned by \Argument{block}. If the receiver is not matched by \Argument{regex} then the string that is returned is a copy of the receiver as if \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html\#//apple\_ref/occ/clm/NSString/stringWithString:}{stringWithString:} had been sent to it.

Returns \Code{NULL} if there was an error.}


\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:}{\RaggedRight{}- stringByReplacingOccurrencesOfRegex:options:inRange:error:\\\hspace{2ex}enumerationOptions:usingBlock:}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{\RegexKitLite{} NSString Additions Reference - Block-based Enumeration Methods}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:}{\protect\texorpdfstring{stringByReplacingOccurrencesOfRegex:options:inRange:error:\protect\linebreak{}enumerationOptions:usingBlock:}{stringByReplacingOccurrencesOfRegex:options:inRange:error:enumerationOptions:usingBlock:}}

Enumerates the matches in the receiver by the regular expression \Argument{regex} within \Argument{range} using \Argument{options} and executes \Argument{block} using \Argument{enumerationOptions} for each match found. Returns a string created by replacing the characters that were matched in the receiver with the contents of the string returned by \Argument{block}.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByReplacingOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{inRange:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error}\\~~~~\Selector{enumerationOptions:}(\RKLCodeRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions})\Argument{enumerationOptions}\\~~~~\Selector{usingBlock:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *(\textasciicircum{})(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger} \Argument{captureCount},\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \Argument{capturedStrings}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~const \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} \Argument{capturedRanges}[captureCount],\\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~volatile \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} * const \Argument{stop}))\Argument{block};}

\begin{RKLParameters}
  \item[regex] A \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[range] The range of the receiver to search.
  \item[error] An optional parameter that if set and an error occurs, will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
  \item[enumerationOptions] A mask of options specified by combining \RKLCodePageRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLRegexEnumerationNoOptions}{RKLRegexEnumerationNoOptions} may be used if no options are required.
  \item[block] The block that is executed for each match of \Argument{regex} in the receiver.  The block takes four arguments:
  \begin{RKLParameters}
    \item[captureCount] The number of strings that \Argument{regex} captured.  \Argument{captureCount} is always at least \Code{1}.
    \item[capturedStrings] An array containing the substrings matched by each capture group present in \Argument{regex}. The size of the array is \Argument{captureCount}. If a capture group did not match anything, it will contain a pointer to a string that is equal to \Code{@""}. This argument may be \Code{NULL} if \Argument{enumerationOptions} had \RKLCodePageRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired} set.
    \item[capturedRanges] An array containing the ranges matched by each capture group present in \Argument{regex}.  The size of the array is \Argument{captureCount}.  If a capture group did not match anything, it will contain a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange} equal to \Code{\{\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/constant\_group/NSNotFound}{NSNotFound}, 0\}}.
    \item[stop] A reference to a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL} value that the block can use to stop the enumeration by setting \linebreak \Code{*}\Argument{stop}\Code{ = \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/macro/YES}{YES};} otherwise it should not touch \Code{*}\Argument{stop}.
  \end{RKLParameters}
\end{RKLParameters}

\RKLReturnValue{A \Code{NSString} created from the characters within \Argument{range} of the receiver in which all matches of the regular expression \Argument{regex} using \Argument{options} are replaced with the contents of the \Code{NSString} returned by \Argument{block}.  Returns the characters within \Argument{range} as if \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html\#//apple\_ref/occ/clm/NSString/substringWithRange:}{substringWithRange:} had been sent to the receiver if the substring is not matched by \Argument{regex}.

Returns \Code{NULL} if there was an error and indirectly returns a \Code{NSError} object if \Argument{error} is not \Code{NULL}.}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:}{- stringByReplacingOccurrencesOfRegex:usingBlock:}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}%
  \item \RKLSectionPageRef{RegularExpressionEnumerationOptions}{Regular Expression Enumeration Options}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{\RegexKitLite{} NSString Additions Reference - Block-based Enumeration Methods}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:}{stringByReplacingOccurrencesOfRegex:withString:}

Returns a string created from the characters of the receiver in which all matches of the regular expression \Argument{regex} are replaced with the contents of the \Argument{replacement} string after performing capture group substitutions.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByReplacingOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{withString:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{replacement};}

\RKLBoxImportant{Raises \RKLCodePageRef{RKLICURegexException}{RKLICURegexException} if \Argument{replacement} contains \Regex{\$}\Argument{n} capture references where \Argument{n} is greater than the number of capture groups in the regular expression \Argument{regex}.}

\RKLReturnValue{A \Code{NSString} created from the characters of the receiver in which all matches of the regular expression \Argument{regex} are replaced with the contents of the \Argument{replacement} string after performing capture group substitutions. If the receiver is not matched by \Argument{regex} then the string that is returned is a copy of the receiver as if \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html\#//apple\_ref/occ/clm/NSString/stringWithString:}{stringWithString:} had been sent to it.

Returns \Code{NULL} if there was an error.}

\RKLAvailability{Available in \RegexKitLite{ 2.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:range:}{- stringByReplacingOccurrencesOfRegex:withString:range:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:options:range:error:}{- stringByReplacingOccurrencesOfRegex:withString:options:range:error:}
  \item \RKLSectionPageRef{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax}
\end{RKLSeeAlso}



\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:range:}{stringByReplacingOccurrencesOfRegex:withString:range:}

Returns a string created from the characters within \Argument{range} of the receiver in which all matches of the regular expression \Argument{regex} are replaced with the contents of the \Argument{replacement} string after performing capture group substitutions.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByReplacingOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{withString:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{replacement} \Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range};}

\RKLBoxImportant{Raises \RKLCodePageRef{RKLICURegexException}{RKLICURegexException} if \Argument{replacement} contains \Regex{\$}\Argument{n} capture references where \Argument{n} is greater than the number of capture groups in the regular expression \Argument{regex}.}

\RKLReturnValue{A \Code{NSString} created from the characters within \Argument{range} of the receiver in which all matches of the regular expression \Argument{regex} are replaced with the contents of the \Argument{replacement} string after performing capture group substitutions.  Returns the characters within \Argument{range} as if \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html\#//apple\_ref/occ/clm/NSString/substringWithRange:}{substringWithRange:} had been sent to the receiver if the substring is not matched by \Argument{regex}.

Returns \Code{NULL} if there was an error.}

\RKLAvailability{Available in \RegexKitLite{ 2.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:}{- stringByReplacingOccurrencesOfRegex:withString:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:options:range:error:}{- stringByReplacingOccurrencesOfRegex:withString:options:range:error:}
  \item \RKLSectionPageRef{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax}
\end{RKLSeeAlso}

\LabeledMethodSelector{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:options:range:error:}{stringByReplacingOccurrencesOfRegex:withString:options:range:error:}

Returns a string created from the characters within \Argument{range} of the receiver in which all matches of the regular expression \Argument{regex} using \Argument{options} are replaced with the contents of the \Argument{replacement} string after performing capture group substitutions.

\SIGNATURE{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Selector{stringByReplacingOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Selector{options:}(\RKLCodeRef{RKLRegexOptions}{RKLRegexOptions})\Argument{options} \Selector{withString:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{replacement}\\~~~~\Selector{range:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSRange}{NSRange})\Argument{range} \Selector{error:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError} **)\Argument{error};}

\begin{RKLParameters}
  \item[regex] A \Code{NSString} containing a regular expression.
  \item[options] A mask of options specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator.  Either \Code{0} or \RKLCodePageRef{RKLNoOptions}{RKLNoOptions} may be used if no options are required.
  \item[replacement] The string to use as the replacement text for matches by \Argument{regex}.  See \RKLSectionPageRef{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax} for more information.
    \RKLBoxImportant{Raises \RKLCodePageRef{RKLICURegexException}{RKLICURegexException} if \Argument{replacement} contains \Regex{\$}\Argument{n} capture references where \Argument{n} is greater than the number of capture groups in the regular expression \Argument{regex}.}
  \item[range] The range of the receiver to search.
  \item[error] An optional parameter that if set and an error occurs, will contain a \Code{NSError} object that describes the problem. This may be set to \Code{NULL} if information about any errors is not required.
\end{RKLParameters}

\RKLReturnValue{A \Code{NSString} created from the characters within \Argument{range} of the receiver in which all matches of the regular expression \Argument{regex} using \Argument{options} are replaced with the contents of the \Argument{replacement} string after performing capture group substitutions.  Returns the characters within \Argument{range} as if \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html\#//apple\_ref/occ/clm/NSString/substringWithRange:}{substringWithRange:} had been sent to the receiver if the substring is not matched by \Argument{regex}.

Returns \Code{NULL} if there was an error and indirectly returns a \Code{NSError} object if \Argument{error} is not \Code{NULL}.}

\RKLAvailability{Available in \RegexKitLite{ 2.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:}{- stringByReplacingOccurrencesOfRegex:withString:}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:range:}{- stringByReplacingOccurrencesOfRegex:withString:range:}
  \item \RKLSectionPageRef{ICUSyntax_ICUReplacementTextSyntax}{ICU Replacement Text Syntax}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
  \item \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options}
\end{RKLSeeAlso}

%\end{RKLMethodsCodeFooter}

%\begin{RKLMethods}


\section{Constants}

\RKLTypeDefSection {RKLRegexOptions}{RKLRegexOptions}

Type for regular expression options.

\Code{typedef uint32\_t RKLRegexOptions;}

\RKLDiscussion{See \RKLSectionPageRef{RegularExpressionOptions}{Regular Expression Options} for possible values.}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\RKLDeclaredIn{RegexKitLite.h}

\labeledsubsection{RegularExpressionOptions}{Regular Expression Options}

The following flags control various aspects of regular expression matching. The flag values may be specified at the time that a regular expression is used, or they may be specified within the pattern itself using the \Regex{(?ismwx-ismwx)} pattern options.

\begin{lstlisting}[escapeinside=``]
enum {
   `\RKLCodeRef{RKLNoOptions}{RKLNoOptions}`             = 0,
   `\RKLCodeRef{RKLCaseless}{RKLCaseless}`              = 2,
   `\RKLCodeRef{RKLComments}{RKLComments}`              = 4,
   `\RKLCodeRef{RKLDotAll}{RKLDotAll}`                = 32,
   `\RKLCodeRef{RKLMultiline}{RKLMultiline}`             = 8,
   `\RKLCodeRef{RKLUnicodeWordBoundaries}{RKLUnicodeWordBoundaries}` = 256
};
\end{lstlisting}

\begin{RKLConstants}
  \RKLConstant{RKLNoOptions}{RKLNoOptions}{No regular expression options specified.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLCaseless}{RKLCaseless}{If set, matching will take place in a case-insensitive manner.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLComments}{RKLComments}{If set, allow use of \RegexDef{white space} and \Regex{\#comments} within patterns.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLDotAll}{RKLDotAll}{If set, a \Regex{.} in a pattern will match a \RegexDef{line terminator} in the input text. By default, it will not. Note that a \RegexDef{carriage-return} / \RegexDef{line-feed} pair in text behave as a single line terminator, and will match a \linebreak single \Regex{.} (period) in a regular expression pattern.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLMultiline}{RKLMultiline}{Control the behavior of \Regex{\textasciicircum{}} and \Regex{\$} in a pattern. By default these will only match at the start and end, respectively, of the input text. If this flag is set, \Regex{\textasciicircum{}} and \Regex{\$} will also match at the start and end of each line within the input text.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLUnicodeWordBoundaries}{RKLUnicodeWordBoundaries}{Controls the behavior of \Regex{\textbackslash{}b} in a pattern. If set, word boundaries are found according to the definitions of word found in \RKLSectionHref{http://www.unicode.org/reports/tr29/}{Unicode UAX 29 - Text Boundaries}. By default, word boundaries are identified by means of a simple classification of characters as either \RegexDef{word} or \RegexDef{non-word}, which approximates traditional regular expression behavior. The results obtained with the two options can be quite different in runs of \RegexDef{spaces} and other \RegexDef{non-word} characters.\\Available in \RegexKitLite{ 1.0} and later.}
\end{RKLConstants}

%\vspace{\stretch{5}}
\begin{RKLDiscussionEnv}

%\vskip-2\parskip{
{Options for controlling the behavior of a regular expression pattern can be controlled in two ways.  When the method supports it, options may specified by combining \RKLCodePageRef{RKLRegexOptions}{RKLRegexOptions} flags with the C bitwise OR operator. For example:}

%\vspace{\stretch{10}}
\begin{lstlisting}
matchedRange = [aString rangeOfRegex:@"^(blue|red)$"
                             options:(RKLCaseless | RKLMultiline)
                             inRange:range
                               error:NULL];
\end{lstlisting}
%\vspace{\stretch{10}}

The other way is to specify the options within the regular expression itself, of which there are two ways.  The first specifies the options for everything following it, and the other sets the options on a per capture group basis. Options are either \It{enabled}, or following a \Regex{-}, \It{disabled}. The syntax for both is nearly identical:

%\vspace{\stretch{5}}
\begin{tabularx}{\textwidth}{|l|l|X|}\hline
\rowcolor[gray]{0.8862745} \Bd{Option} & \Bd{Example} & \Bd{Description}\\\hline
\Regex{(?}\Argument{ixsmw}\Regex{-}\Argument{ixsmw}\Regex{)}\textellipsis{} & \Regex{(?i)}\textellipsis{} & Enables the \RKLCodeRef{RKLCaseless}{RKLCaseless} option for everything that follows it.  Useful at the beginning of a regular expression to set the desired options.\\\hline
\Regex{(?}\Argument{ixsmw}\Regex{-}\Argument{ixsmw}\Regex{:}\textellipsis{}\Regex{)} & \Regex{(?iw-m:}\textellipsis{}\Regex{)} & Enables the \RKLCodeRef{RKLCaseless}{RKLCaseless} and \RKLCodeRef{RKLUnicodeWordBoundaries}{RKLUnicodeWordBoundaries} options and disables \RKLCodeRef{RKLMultiline}{RKLMultiline} for the capture group enclosed by the parenthesis.\\\hline
\end{tabularx}

%\vspace{\stretch{5}}
The following table lists the regular expression pattern option character and its corresponding \linebreak \RKLCodeRef{RKLRegexOptions}{RKLRegexOptions} flag:

%\vspace{\stretch{30}}
%\pagebreak
\begin{tabular}{|l|l|}\hline
\rowcolor[gray]{0.8862745} \Bd{Character} & \Bd{Option}\\\hline
\Regex{i} & \RKLCodeRef{RKLCaseless}{RKLCaseless}\\\hline
\Regex{x} & \RKLCodeRef{RKLComments}{RKLComments}\\\hline
\Regex{s} & \RKLCodeRef{RKLDotAll}{RKLDotAll}\\\hline
\Regex{m} & \RKLCodeRef{RKLMultiline}{RKLMultiline}\\\hline
\Regex{w} & \RKLCodeRef{RKLUnicodeWordBoundaries}{RKLUnicodeWordBoundaries}\\\hline
\end{tabular}
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLSectionPageRef{ICUSyntax_ICURegularExpressionSyntax}{ICU Regular Expression Syntax}
  \item \RKLSectionHref{http://userguide.icu-project.org/strings/regexp}{ICU User Guide - Regular Expressions}
\end{RKLSeeAlso}

\RKLDeclaredIn{RegexKitLite.h}



\RKLTypeDefSection{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions}

Type for regular expression enumeration options.

\Code{typedef NSUInteger RKLRegexEnumerationOptions;}

\begin{RKLDiscussionEnv}
See \RKLSectionPageRef{RegularExpressionEnumerationOptions}{Regular Expression Enumeration Options} for possible values.

\RKLBoxImportant{\Code{RKLRegexEnumerationOptions} is only available if \CPPFlag{RKL\_BLOCKS} is set.}
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\RKLDeclaredIn{RegexKitLite.h}




\labeledsubsection{RegularExpressionEnumerationOptions}{Regular Expression Enumeration Options}

The following flags control various aspects of regular expression enumeration.

\begin{lstlisting}[escapeinside=``]
enum {
   `\RKLCodeRef{RKLRegexEnumerationNoOptions}{RKLRegexEnumerationNoOptions}`                               = 0UL,
   `\RKLCodeRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired}`              = 1UL << 9,
   `\RKLCodeRef{RKLRegexEnumerationReleaseStringReturnedByReplacementBlock}{RKLRegexEnumerationReleaseStringReturnedByReplacementBlock}` = 1UL << 10,
   `\RKLCodeRef{RKLRegexEnumerationFastCapturedStringsXXX}{RKLRegexEnumerationFastCapturedStringsXXX}`                  = 1UL << 11
};
\end{lstlisting}


\begin{RKLConstants}

  \RKLConstant{RKLRegexEnumerationNoOptions}{RKLRegexEnumerationNoOptions}{No regular expression enumeration options specified.\\Available in \RegexKitLite{ 4.0} and later.}
    
  \RKLConstant{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired}{If set, this indicates that the block does not require the captured strings and \Code{NULL} will be passed to the blocks \Argument{capturedStrings}\Code{[]} argument.

\RKLBoxImportant{Methods will raise \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSInvalidArgumentException}{NSInvalidArgumentException} if \RKLCodePageRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegex\DLBrk{}Enu\DLBrk{}mer\DLBrk{}ation\DLBrk{}\DLBrk{}Cap\DLBrk{}tured\DLBrk{}Strings\DLBrk{}Not\DLBrk{}Required} and \RKLCodePageRef{RKLRegexEnumerationFastCapturedStringsXXX}{RKLRegex\DLBrk{}Enu\DLBrk{}mer\DLBrk{}ation\DLBrk{}Fast\DLBrk{}Cap\DLBrk{}tured\DLBrk{}Str\DLBrk{}ingsXXX} are both set.}

Available in \RegexKitLite{ 4.0} and later.}
    
  \RKLConstant{RKLRegexEnumerationReleaseStringReturnedByReplacementBlock}{RKLRegexEnumerationReleaseStringReturnedByReplacementBlock}{If set, \RegexKitLite{} will send the string returned by the block a \Code{release} message.  If garbage collection is active, this flag does nothing.  This flag is only valid for the \Code{stringByReplacingOccurrencesOfRegex:}\textellipsis{} and \Code{replaceOccurrencesOfRegex:}\textellipsis{} groups of methods. See \RKLSectionPageRef{RKLRegexEnumerationOptions__Discussion_RKLRegexEnumerationReleaseStringReturnedByReplacementBlock}{Regular Expression Enumeration Options - Using RKLRegexEnumerationReleaseStringReturnedByReplacementBlock} for more information.

\RKLBoxImportant{Methods will raise \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSInvalidArgumentException}{NSInvalidArgumentException} if %
\RKLCodePageRef{RKLRegexEnumerationReleaseStringReturnedByReplacementBlock}{RKLRegexEnu\DLBrk{}mer\DLBrk{}ation\DLBrk{}Re\DLBrk{}lease\DLBrk{}StringReturnedByReplacementBlock}  is set and the block enumeration method is not a 'Search and Replace' method.}

Available in \RegexKitLite{ 4.0} and later.}

    
  \RKLConstant{RKLRegexEnumerationFastCapturedStringsXXX}{RKLRegexEnumerationFastCapturedStringsXXX}{If set, \RegexKitLite{} will create the captured strings that are passed to the blocks \Argument{capturedStrings}\Code{[]} argument in a special way.  The enumeration identifier ends in \textellipsis{}\Code{XXX} to act as a visual reminder that special care must be taken.   See \RKLSectionPageRef{RKLRegexEnumerationOptions__Discussion_RKLRegexEnumerationFastCapturedStringsXXX}{Regular Expression Enumeration Options - Using RKLRegexEnumerationFastCapturedStringsXXX} for more information.

\RKLBoxImportant{Methods will raise \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSInvalidArgumentException}{NSInvalidArgumentException} if \RKLCodePageRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegex\DLBrk{}Enu\DLBrk{}mer\DLBrk{}a\DLBrk{}tion\DLBrk{}\DLBrk{}Cap\DLBrk{}tured\DLBrk{}Strings\DLBrk{}Not\DLBrk{}Required} and \RKLCodePageRef{RKLRegexEnumerationFastCapturedStringsXXX}{RKLRegex\DLBrk{}Enu\DLBrk{}mer\DLBrk{}a\DLBrk{}tion\DLBrk{}Fast\DLBrk{}Cap\DLBrk{}tured\DLBrk{}Str\DLBrk{}ingsXXX} are both set.}

\vskip-\parskip\vskip-\parskip
\RKLBoxCaution{\RKLCodePageRef{RKLRegexEnumerationFastCapturedStringsXXX}{RKLRegexEnumerationFastCapturedStringsXXX} is an advanced feature option.  \BdItUl{Do not} use this option unless you fully understand the consequences.  Incorrect usage of this option will result in undefined behavior and will probably result in your program crashing.}

Available in \RegexKitLite{ 4.0} and later.}

\end{RKLConstants}


\begin{RKLDiscussionEnv}\label{RKLRegexEnumerationOptions__Discussion}
\vskip-\parskip\vskip-\parskip
\RKLBoxImportant{\Code{RKLRegexEnumerationOptions} is only available if \CPPFlag{RKL\_BLOCKS} is set.}

When the method supports it, enumeration options may specified by combining \RKLCodePageRef{RKLRegexEnumerationOptions}{RKLRegexEnu\DLBrk{}mer\DLBrk{}ationOp\DLBrk{}tions} flags with the C bitwise OR operator. For example:

\begin{lstlisting}
RKLRegexEnumerationOptions enumerationOptions = 
                        (RKLRegexEnumerationCapturedStringsNotRequired |
                         RKLRegexEnumerationReleaseStringReturnedByReplacementBlock);
\end{lstlisting}

\vskip-\parskip
A typical use of \Code{stringByReplacingOccurrencesOfRegex:} might be something like the following:

\begin{lstlisting}
replacedString = 
   [aString stringByReplacingOccurrencesOfRegex:@"\\w+"
                                        options:RKLNoOptions
                                        inRange:NSMakeRange(0UL, [aString length])
                                          error:NULL
                             enumerationOptions:RKLRegexEnumerationNoOptions
                                     usingBlock:
                                    ^(NSInteger captureCount,
                                      NSString * const capturedStrings[captureCount],
                                      const NSRange capturedRanges[captureCount],
                                      volatile BOOL * const stop) {
  return((NSString *)[NSString stringWithFormat:@"<%@>", capturedStrings[0]]);
}];
\end{lstlisting}

\RKLBoxNote{The above example casts the value returned by \Code{stringWithFormat:}, which has a return type of \Code{id}, to \Code{NSString *} because of a bug in \HardNobr{\ConsoleText{gcc} \Code{4.2.1-5646}.}  Without the cast, the compiler gives an error that the block does not return a compatible type.  \ConsoleText{clang} does not require a cast in order to compile.}

An alternate way to work around the \ConsoleText{gcc} bug is to explicitly declare the return type of the block.  The example below shows how this is done with the changes highlighted:

\begin{lstlisting}[escapeinside=``]
`\Code{\It{stringByReplacingOccurrencesOfRegex:\textellipsis{}}}` usingBlock:
                          ^`\RKLHighlightRect{\Code{NSString *}}`(NSInteger captureCount,
                                       NSString * const capturedStrings[captureCount],
                                       const NSRange capturedRanges[captureCount],
                                       volatile BOOL * const stop) {
  return(`\RKLHighlightRect{/*(NSString *)*/}`[NSString stringWithFormat:@"<%@>", capturedStrings[0]]);
}];
\end{lstlisting}

\par\textbf{Using \Code{RKLRegexEnumerationReleaseStringReturnedByReplacementBlock}}\label{RKLRegexEnumerationOptions__Discussion_RKLRegexEnumerationReleaseStringReturnedByReplacementBlock}\newline

The use of convenience methods like \Code{stringWithFormat:} can create a lot of temporary strings that are autoreleased.  The memory used to hold these temporary strings won't be reclaimed until the autorelease pool that they are in is released.  When performing a replace on a large string, this can end up being a considerable amount of memory.  If this is becomes a problem in your application, the \Code{RKLRegex\DLBrk{}Enu\DLBrk{}mer\DLBrk{}a\DLBrk{}tion\DLBrk{}Re\DLBrk{}lease\DLBrk{}StringReturnedByReplacementBlock} enumeration option can be used to reclaim the memory used by these temporary strings immediately.  \Code{RKLRegexEnumerationReleaseStringReturned\DLBrk{}By\DLBrk{}Re\DLBrk{}place\DLBrk{}ment\DLBrk{}Block} essentially transfers ownership of the string that is returned by the block to \RegexKitLite{,} which then becomes responsible for sending the string a \Code{release} message when it is no longer needed.  Typically this is right after \RegexKitLite{} has appended the contents of the returned string to the temporary internal string of all the accumulated replacement strings returned by the block.  For example:

\begin{lstlisting}
replacedString = [aString stringByReplacingOccurrencesOfRegex:@"\\w+"
                     options:RKLNoOptions
                     inRange:NSMakeRange(0UL, [aString length])
                       error:NULL
          enumerationOptions:RKLRegexEnumerationReleaseStringReturnedByReplacementBlock
                  usingBlock:
                     ^NSString *(NSInteger captureCount,
                                 NSString * const capturedStrings[captureCount],
                                 const NSRange capturedRanges[captureCount],
                                 volatile BOOL * const stop) {
  return([[NSString alloc] initWithFormat:@"<%@>", capturedStrings[0]]);
}];
\end{lstlisting}

When using \Code{RKLRegexEnumerationReleaseStringReturnedByReplacementBlock}, it is also possible to directly return the strings that were passed via \Argument{capturedStrings}\Code{[]}.  \RegexKitLite{} automatically checks if the pointer of the string returned by the block is equal to the pointer of any of the strings it created and passed via \Argument{capturedStrings}\Code{[]}, in which case \RegexKitLite{} does not send the string that was returned a \Code{release} message since this would result in over releasing the string object.  For example:

\begin{lstlisting}
replacedString = [aString stringByReplacingOccurrencesOfRegex:@"\\w+"
                     options:RKLNoOptions
                     inRange:NSMakeRange(0UL, [aString length])
                       error:NULL
          enumerationOptions:RKLRegexEnumerationReleaseStringReturnedByReplacementBlock
                  usingBlock:
                     ^NSString *(NSInteger captureCount,
                                 NSString * const capturedStrings[captureCount],
                                 const NSRange capturedRanges[captureCount],
                                 volatile BOOL * const stop) {
  if([capturedStrings[0] isEqual:@"with"]) { return(capturedStrings[0]); }
  else { return([[NSString alloc] initWithFormat:@"<%@>", capturedStrings[0]]); }
}];
\end{lstlisting}

\par\textbf{Using \Code{RKLRegexEnumerationFastCapturedStringsXXX}}\label{RKLRegexEnumerationOptions__Discussion_RKLRegexEnumerationFastCapturedStringsXXX}\newline

Normally, \RegexKitLite{} instantiates a new string object for each string passed via \Argument{capturedStrings}\Code{[]}. When \RKLCodeRef{RKLRegexEnumerationFastCapturedStringsXXX}{RKLRegexEnumerationFastCapturedStringsXXX} is set, \RegexKitLite{} creates up to \Argument{captureCount} strings using the \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation} function \RKLCodeHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CFMutableStringRef/Reference/reference.html\#//apple\_ref/c/func/CFStringCreateMutableWithExternalCharactersNoCopy}{CFStringCreateMutableWithExternalCharactersNoCopy} and passes these strings via \Argument{capturedStrings}\Code{[]}.

\RKLBoxCaution{\RKLCodeRef{RKLRegexEnumerationFastCapturedStringsXXX}{RKLRegexEnumerationFastCapturedStringsXXX} is an advanced feature option.  \BdItUl{Do not} use this option unless you fully understand the consequences.  Incorrect usage of this option will result in undefined behavior and will probably result in your program crashing.}

The reason for doing this is strings created with \RKLCodeHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CFMutableStringRef/Reference/reference.html\#//apple\_ref/c/func/CFStringCreateMutableWithExternalCharactersNoCopy}{CFStringCreateMutableWithExternalCharactersNoCopy} can have the strings buffer set directly with \RKLCodeHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CFMutableStringRef/Reference/reference.html\#//apple\_ref/c/func/CFStringSetExternalCharactersNoCopy}{CFStringSetExternalCharactersNoCopy}. This allows\DLBRK{} \RegexKitLite{} to quickly update the strings that were captured by a match and is \BdIt{much} faster than instantiating new strings for each match iteration since the only thing that needs to be updated is the captured strings pointer and length. In fact, the speed of \RKLCodeRef{RKLRegexEnumerationFastCapturedStringsXXX}{RKLRegexEnumerationFastCapturedStringsXXX} is nearly has fast as \RKLCodeRef{RKLRegexEnumerationCapturedStringsNotRequired}{RKLRegexEnumerationCapturedStringsNotRequired}.

{\RaggedRight{}Special care must be taken when using the strings passed via \Argument{capturedStrings}\Code{[]} when \linebreak \RKLCodeRef{RKLRegexEnumerationFastCapturedStringsXXX}{RKLRegexEnumerationFastCapturedStringsXXX} has been set.  The following rules must be followed:}

\begin{RKLBulletList}
  \item The lifetime of the string is the duration of the blocks execution.  The string \BdIt{can not} be used or referenced past the closing brace of the block.
  \item \BdItUl{Do not} mutate any of \Argument{capturedStrings}\Code{[]}.
  \item \BdItUl{Do not} \Code{retain} or \Code{release} any of the \Argument{capturedStrings}\Code{[]}.
  \item If you need the string to exist past the end of the block, a \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSObject\_Class/Reference/Reference.html\#//apple\_ref/occ/instm/NSObject/copy}{-copy} of the string must be made:

\begin{lstlisting}
NSString *copiedString = [[capturedStrings[0] copy] autorelease];
\end{lstlisting}

\end{RKLBulletList}

\vskip-\parskip\vskip-\parskip
Example usages:

\begin{RKLBulletList}
  \item When using \Argument{capturedStrings}\Code{[]} as an argument to \Code{stringWithFormat:}, you do not need to make a copy of the captured string:

\begin{lstlisting}
[searchString stringByReplacingOccurrencesOfRegex:regex
                  usingBlock:
                     ^NSString *(NSInteger captureCount,
                                 NSString * const capturedStrings[captureCount],
                                 const NSRange capturedRanges[captureCount],
                                 volatile BOOL * const stop) {
  NSString *replacedString = NULL;
  // An example of when it is safe to use capturedStrings[] directly.
  replacedString = [NSString stringWithFormat:@"{1: '%@'}", capturedStrings[1]];
  return(replacedString);
}];
\end{lstlisting}

  \item Adding to a collection:

\begin{lstlisting}[escapeinside=``]
// `\Code{\BdItUl{Do not}}` add a captured string directly to a collection.
[aDictionary setObject:capturedStrings[0] forKey:@"aKey"];

// `\Code{\BdItUl{Do}}` add a copy of the captured string to a collection.
[aDictionary setObject:[[capturedStrings[0] copy] autorelease] forKey:@"aKey"];
\end{lstlisting}

  \item Assigning a captured string to a variable whose scope extends past the blocks:

\begin{lstlisting}[escapeinside=``]
__block NSString *foundString = NULL;

[searchString enumerateStringsMatchedByRegex:regex
                                  usingBlock:
                                 ^(NSInteger captureCount,
                                   NSString * const capturedStrings[captureCount],
                                   const NSRange capturedRanges[captureCount],
                                   volatile BOOL * const stop) {

  // `\Code{\BdItUl{Do not}}` assign a captured string to a variable 
  //        whose scope extends past the Blocks.
  foundString = capturedStrings[0];

  // `\Code{\BdItUl{Do}}` assign a copy of the captured string to a
  //    variable whose scope extends past the Blocks.
  foundString = [[capturedStrings[0] copy] autorelease];
}];
\end{lstlisting}

\end{RKLBulletList}
\end{RKLDiscussionEnv}

\RKLAvailability{Available in \RegexKitLite{ 4.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLSectionPageRef{RegexKitLiteNSStringAdditionsReference_Block-basedEnumerationMethods}{\RegexKitLite{} NSString Additions Reference - Block-based Enumeration Methods}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Conceptual/Blocks/Articles/00\_Introduction.html}{Blocks Programming Topics}
\end{RKLSeeAlso}

\RKLDeclaredIn{RegexKitLite.h}



\labeledsubsection{dtrace_utf16ConversionCache_lookupResultFlags}{RegexKitLite:::utf16ConversionCache \protect\texorpdfstring{\Argument{arg1}}{arg1} Flags}

The following flags are used to indicate the status of the result from \Argument{arg1} \Argument{lookupResultFlags} of the\linebreak \Code{RegexKitLite:::utf16ConversionCache} DTrace probe point.

\begin{lstlisting}[escapeinside=``]
enum {
   `\RKLCodeRef{RKLCacheHitLookupFlag}{RKLCacheHitLookupFlag}`           = 1 << 0,
   `\RKLCodeRef{RKLConversionRequiredLookupFlag}{RKLConversionRequiredLookupFlag}` = 1 << 1,
   `\RKLCodeRef{RKLSetTextLookupFlag}{RKLSetTextLookupFlag}`            = 1 << 2,
   `\RKLCodeRef{RKLDynamicBufferLookupFlag}{RKLDynamicBufferLookupFlag}`      = 1 << 3,
   `\RKLCodeRef{RKLErrorLookupFlag}{RKLErrorLookupFlag}`              = 1 << 4,
   `\RKLCodeRef{RKLEnumerationBufferLookupFlag}{RKLEnumerationBufferLookupFlag}`  = 1 << 5
};
\end{lstlisting}

\begin{RKLConstants}
  \RKLConstant{RKLCacheHitLookupFlag}{RKLCacheHitLookupFlag}{If set, there was a successful lookup hit.  This flag is only set if \Code{RKLConversionRequiredLookupFlag} is also set.\\Available in \RegexKitLite{ 3.0} and later.}
  \RKLConstant{RKLConversionRequiredLookupFlag}{RKLConversionRequiredLookupFlag}{If set, direct access to a strings \UTF{16} buffer was not available and a conversion was required.\\Available in \RegexKitLite{ 3.0} and later.}
  \RKLConstant{RKLSetTextLookupFlag}{RKLSetTextLookupFlag}{If set, the ICU \Code{uregex\_setText()} function was called in order to set the compiled regular expression to a buffer.\\Available in \RegexKitLite{ 3.0} and later.}
  \RKLConstant{RKLDynamicBufferLookupFlag}{RKLDynamicBufferLookupFlag}{If set, the strings size was large enough to require the use of the dynamically sized conversion buffer.\\Available in \RegexKitLite{ 3.0} and later.}
  \RKLConstant{RKLErrorLookupFlag}{RKLErrorLookupFlag}{If set, there was some kind of error during the \UTF{16} conversion process.\\Available in \RegexKitLite{ 3.0} and later.}
  \RKLConstant{RKLEnumerationBufferLookupFlag}{RKLEnumerationBufferLookupFlag}{If set, the probe was fired due to a blocks enumeration.  The conversion result is one time use only and is only available to the block enumeration that required it.\\Available in \RegexKitLite{ 4.0} and later.}
\end{RKLConstants}

\begin{RKLSeeAlso}
  \item \RKLCodePageRef{DTrace_RegexKitLiteProbePoints__utf16ConversionCache}{RegexKitLite:::utf16ConversionCache}
\end{RKLSeeAlso}

\labeledsubsection{RegexKitLiteNSErrorErrorDomains}{\protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} NSError Error Domains}

The following \Code{NSError} error domains are defined.

\Code{extern \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \RKLCodeRef{RKLICURegexErrorDomain}{RKLICURegexErrorDomain};}

\begin{RKLConstants}
  \RKLConstant{RKLICURegexErrorDomain}{RKLICURegexErrorDomain}{ICU Regular Expression Errors.}
\end{RKLConstants}

\RKLAvailability{Available in \RegexKitLite{ 1.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError Class Reference}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
\end{RKLSeeAlso}

\RKLDeclaredIn{RegexKitLite.h}

%\vskip-4\parskip
%
%\vskip-4\parskip

\labeledsubsection{RegexKitLiteNSExceptionExceptionNames}{\protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} NSException Exception Names}

The following \Code{NSException} exception names are defined.

\Code{extern \RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} * const \RKLCodeRef{RKLICURegexException}{RKLICURegexException};}

\begin{RKLConstants}
  \RKLConstant{RKLICURegexException}{RKLICURegexException}{ICU Regular Expression Exceptions}
\end{RKLConstants}

\RKLDiscussion{Returns a user info dictionary populated with keys as defined in \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}.}

\RKLAvailability{Available in \RegexKitLite{ 2.0} and later.}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSException\_Class/Reference/Reference.html}{NSException Class Reference}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}
\end{RKLSeeAlso}

\RKLDeclaredIn{RegexKitLite.h}
%
%\vskip-4\parskip
%
%\vskip-4\parskip

\labeledsubsection{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\protect\texorpdfstring{\RegexKitLite{}}{RegexKitLite} NSError and NSException User Info Dictionary Keys}

\begin{lstlisting}[escapeinside=``]
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexEnumerationOptionsErrorKey}{RKLICURegexEnumerationOptionsErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexErrorCodeErrorKey}{RKLICURegexErrorCodeErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexErrorNameErrorKey}{RKLICURegexErrorNameErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexLineErrorKey}{RKLICURegexLineErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexOffsetErrorKey}{RKLICURegexOffsetErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexPreContextErrorKey}{RKLICURegexPreContextErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexPostContextErrorKey}{RKLICURegexPostContextErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexRegexErrorKey}{RKLICURegexRegexErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexRegexOptionsErrorKey}{RKLICURegexRegexOptionsErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexReplacedCountErrorKey}{RKLICURegexReplacedCountErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexReplacedStringErrorKey}{RKLICURegexReplacedStringErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexReplacementStringErrorKey}{RKLICURegexReplacementStringErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexSubjectRangeErrorKey}{RKLICURegexSubjectRangeErrorKey}`;
extern `\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString}` * const `\RKLCodeRef{RKLICURegexSubjectStringErrorKey}{RKLICURegexSubjectStringErrorKey}`;
\end{lstlisting}

\begin{RKLConstants}
  \RKLConstant{RKLICURegexEnumerationOptionsErrorKey}{RKLICURegexEnumerationOptionsErrorKey}{The \RKLCodePageRef{RKLRegexEnumerationOptions}{RKLRegexEnumerationOptions} enumeration options specified.\\Available in \RegexKitLite{ 4.0} and later.}
  \RKLConstant{RKLICURegexErrorCodeErrorKey}{RKLICURegexErrorCodeErrorKey}{The error code returned by the ICU library function calls \Argument{status} argument.\\Available in \RegexKitLite{ 2.0} and later.}
  \RKLConstant{RKLICURegexErrorNameErrorKey}{RKLICURegexErrorNameErrorKey}{The string returned by invoking \RKLCodeHref{http://www.icu-project.org/apiref/icu4c/utypes\_8h.html\#89eb455526bb29bf5350ee861d81df92}{u\_errorName} with the error code \RKLCodeRef{RKLICURegexErrorCodeErrorKey}{\Code{RKLICURegexErrorCodeErrorKey}}.  \linebreak Example: \Code{U\_REGEX\_RULE\_SYNTAX}.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLICURegexLineErrorKey}{RKLICURegexLineErrorKey}{The line number where the error occurred in the regular expression.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLICURegexOffsetErrorKey}{RKLICURegexOffsetErrorKey}{The offset from the beginning of the line where the error occurred in the regular expression.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLICURegexPreContextErrorKey}{RKLICURegexPreContextErrorKey}{Up to \Code{16} characters leading up to the cause of the error in the regular expression.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLICURegexPostContextErrorKey}{RKLICURegexPostContextErrorKey}{Up to \Code{16} characters after the cause error in the regular expression.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLICURegexRegexErrorKey}{RKLICURegexRegexErrorKey}{The regular expression that caused the error.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLICURegexRegexOptionsErrorKey}{RKLICURegexRegexOptionsErrorKey}{The \RKLCodeRef{RKLRegexOptions}{RKLRegexOptions} regular expression options specified.\\Available in \RegexKitLite{ 1.0} and later.}
  \RKLConstant{RKLICURegexReplacedCountErrorKey}{RKLICURegexReplacedCountErrorKey}{The number of times a replacement was performed.\\Available in \RegexKitLite{ 4.0} and later.}
  \RKLConstant{RKLICURegexReplacedStringErrorKey}{RKLICURegexReplacedStringErrorKey}{The replaced string result after performing the search and replace operations.\\Available in \RegexKitLite{ 4.0} and later.}
  \RKLConstant{RKLICURegexReplacementStringErrorKey}{RKLICURegexReplacementStringErrorKey}{The replacement template string used to perform search and replace operations.\\Available in \RegexKitLite{ 4.0} and later.}
  \RKLConstant{RKLICURegexSubjectRangeErrorKey}{RKLICURegexSubjectRangeErrorKey}{The range of the subject string that was being matched by the regular expression.\\Available in \RegexKitLite{ 4.0} and later.}
  \RKLConstant{RKLICURegexSubjectStringErrorKey}{RKLICURegexSubjectStringErrorKey}{The string that was being matched by the regular expression.\\Available in \RegexKitLite{ 4.0} and later.}
\end{RKLConstants}

\RKLDiscussion{Different error keys will be present depending on the type of error encountered.}

\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSError\_Class/Reference/Reference.html}{NSError Class Reference}
  \item \RKLSectionHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSException\_Class/Reference/Reference.html}{NSException Class Reference}
  \item \RKLSectionPageRef{RegexKitLiteNSErrorErrorDomains}{\RegexKitLite{} NSError Error Domains}
  \item \RKLSectionPageRef{RegexKitLiteNSExceptionExceptionNames}{\RegexKitLite{} NSException Exception Names}
\end{RKLSeeAlso}

\RKLDeclaredIn{RegexKitLite.h}

\end{RKLMethods}

\labeledchapter{ReleaseInformation}{Release Information}

\titleformat{\section}{\normalfont\large}{\thesection.}{.5em}{}[\vspace{1.5pt}\titlerule]
\titlespacing{\section}{0pt}{*3}{*1.25}

\section{1.0 - 2008/03/23}
\label{ReleaseInformation_10}

Initial release.
    
\section{1.1 - 2008/03/28}
\label{ReleaseInformation_11}

Changes:

\begin{RKLBulletList}
  \item Added the method \RKLCodePageRef{NSString_RegexKitLiteAdditions__.clearStringCache}{clearStringCache}.
  \item Updated the documentation with information about searching \Code{NSMutableString} strings, and when to use \RKLCodePageRef{NSString_RegexKitLiteAdditions__.clearStringCache}{clearStringCache}.
\end{RKLBulletList}

Bug fixes:

\begin{RKLBulletList}
  \item Fixed a bug that for strings that required \UTF{16} conversion, the conversion from the previous string that required conversion may have been re-used for the current string, even though the two strings are different and the new string requires conversion.
  \item Updated the internal inconsistency exception macro to correctly handle non-\Code{ASCII} file names.
\end{RKLBulletList}

\section{1.2 - 2008/04/01}
\label{ReleaseInformation_12}

Changes:

\begin{RKLBulletList}
  \item Updated and clarified the documentation regarding adding \RegexKitLite{} to an Xcode project.
  \item Created Xcode 3 DocSet documentation.
\end{RKLBulletList}

\section{2.0 - 2008/07/07}
\label{ReleaseInformation_20}

New features:

\begin{RKLBulletList}
  \item The ability to split a string in to a \Code{NSArray} with a regular expression.
  \item Search and replace using common \Regex{\$}\Argument{n} capture substitution in the replacement string.
  \item Support for Leopards Garbage Collection
\end{RKLBulletList}

Changes:

\begin{RKLBulletList}

  \item A new compile time configuration option, \CPPFlag{RKL\_FAST\_MUTABLE\_CHECK}, enables the use of a private, non-public \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation} function to determine if the string that will be searched is immutable.  This allows many of the mutation safety checks to be skipped for that string and can significantly improve the performance of repeated matches on the same immutable \Code{NSString}.  For safety, this option is disabled by default.

  \item Gives a warning at compile time if the minimum \MacOSX{}{} target \HardNobr{is < 10.3,} which is the first version that shipped with the ICU library.

  \item Compile time tunable setting of how much of the stack can be used before switching to heap based storage.  Changed by setting \CPPFlag{RKL\_STACK\_LIMIT} to the maximum number of bytes to use from the stack.  Defaults to \Code{131072}, or \Code{128Kbytes}.  By default in Cocoa the main thread has a stack size of \Code{8Mbytes} and additional threads have a stack size of \Code{512Kbytes}.

  \item New \Code{NSException} name for \RegexKitLite{} specific exceptions, \RKLCodePageRef{RKLICURegexException}{RKLICURegexException}.

  \item Garbage Collection is safe to use in "mixed-mode" Garbage Collection applications.  When compiled with Garbage Collection support \HardNobr{(\Code{-fobjc-gc}),} \RegexKitLite{} will dynamically select either Garbage Collection or manual memory management at run-time depending on whether or not Garbage Collection is enabled and active. 

\end{RKLBulletList}

New \Code{NSString} Methods:

\begin{RKLBulletList}

  \item \Code{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\Bd{componentsSeparatedByRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

  \item \Code{\RaggedRight - (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Bd{stringByReplacingOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Bd{withString:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{replacement};}

\end{RKLBulletList}

New \Code{NSMutableString} Methods:

\begin{RKLBulletList}

  \item \Code{\RaggedRight - (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSUInteger}{NSUInteger})\Bd{replaceOccurrencesOfRegex:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex}\\~~~~\Bd{withString:}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{replacement};}

\end{RKLBulletList}

\section{2.1 - 2008/07/12}
\label{ReleaseInformation_21}

Bug fixes:

\begin{RKLBulletList}
  \item Fixed a bug dealing with the \UTF{16} conversion cache.  A bug could cause the text in the conversion buffer to be incorrectly used for the wrong string.
\end{RKLBulletList}

\section{2.2 - 2008/10/19}
\label{ReleaseInformation_22}

This release contains several large documentation additions and a few bug fixes.  No new major functionality was added.

Documentation Changes:

\begin{RKLBulletList}

  \item Added a section covering \RKLSectionPageRef{ICUSyntax_ICURegularExpressionCharacterClasses}{ICU Regular Expression Character Classes}

  \item Added a section covering \RKLSectionPageRef{ICUSyntax_UnicodeProperties}{Unicode Properties}, which are specified in a regular expression with \linebreak \Regex{\textbackslash{}p\{}\It{Unicode Property Name}\Regex{\}} and \Regex{\textbackslash{}P\{}\It{Unicode Property Name}\Regex{\}}.

  \item Added the \RKLSectionPageRef{RegexKitLiteCookbook}{\RegexKitLite{} Cookbook} section.  Special \It{Copy to Clipboard} functionality is enabled for Safari users that allows a regular expression in this document that is selected and \It{Copied to the Clipboard} to be automatically escaped so the regular expression can be pasted directly in to your source code, ready to be used, with no additional work required.

  \item Added the \RKLSectionPageRef{Epilogue}{Epilogue} section.  This section is meant to be less formal, where I can place bits and pieces that don't fit elsewhere or editorialize on some topic.

  \item A number of small additions, deletions, and edits through out the documentation.
\end{RKLBulletList}

Changes:

\begin{RKLBulletList}

  \item A new compile time configuration option, \CPPFlag{RKL\_METHOD\_PREPEND}, can be used to add custom prefix to all the \RegexKitLite{} methods.  For example, setting \CPPFlag{RKL\_METHOD\_PREPEND} to \Code{xyz\_} would\DLBRk{} cause\DLBRk{} \Code{string\DLBrk{}By\DLBRk{}Re\DLBRk{}placingOc\DLBrk{}cur\DLBrk{}rencesOfRegex:withString:} to become \Code{xyz\_string\DLBrk{}By\DLBrk{}Re\DLBrk{}placing\DLBrk{}Oc\DLBrk{}cur\DLBrk{}rences\DLBrk{}Of\DLBrk{}Regex:withString:}.  This is for users who prefer that any category additions to the core classes, such as \Code{NSString}, have a user defined prefix to prevent the possibility of user defined method names interfering with later system defined method names.

  \item Support for iPhone low memory notifications.  When it can be determined at compile time that the iPhone is being targeted, the preprocessor flag \CPPFlag{RKL\_REGISTER\_FOR\_IPHONE\_LOWMEM\_NOTIFICATIONS} is enabled to add code that automatically registers for low memory notifications on the iPhone.  When a low memory notification is received, \RegexKitLite{} will flush all its caches, freeing the memory used to hold the cached data.

\end{RKLBulletList}

Bug fixes:

\begin{RKLBulletList}

  \item \RKLHref{http://sourceforge.net/tracker/?func=detail\&aid=2105213\&group\_id=\%20204582\&atid=990188}{Bug 2105213}\\

Fixed a bug in \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:}{stringByReplacingOccurrencesOfRegex:withString:} and \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:}{re\DLBrk{}placeOc\DLBrk{}cur\DLBrk{}rences\DLBrk{}OfRegex:withString:} where if the receiver was an empty string (i.e., \Code{@""}), then \RegexKitLite{} would throw an exception because the ICU library reported an error.  This turned out to be a bug in the ICU library itself in the \Code{uregex\_reset()} function (and the methods it calls to perform its work).  A bug was opened with the ICU project: ICU ticket \#\RKLHref{http://bugs.icu-project.org/trac/ticket/6545}{6545}.  A work-around for the buggy behavior was put in place so that if the ICU library reports a \Code{U\_INDEX\_OUTOFBOUNDS\_ERROR} error for a string with a length of zero, that error is ignored since it is spurious.  Thanks go to Andy Kim for reporting this.

  \item \RKLHref{http://sourceforge.net/tracker/?func=detail\&aid=2050825\&group\_id=\%20204582\&atid=990188}{Bug 2050825}\\

Fixed a bug with \Code{NSScannedOption} when targeting the iPhone.  \Code{NSScannedOption} is not available on the iPhone, so C preprocessor statements were added to ensure that \Code{NSScannedOption} is not referenced when Objective-C Garbage Collection is not enabled.  Thanks go to Shaun Inman for reporting this first.

  \item Fixed a bug in \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:withString:}{stringByReplacingOccurrencesOfRegex:withString:} and \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:withString:}{re\DLBrk{}placeOc\DLBrk{}cur\DLBrk{}rences\DLBrk{}Of\DLBrk{}Regex:withString:} where an internal assertion exception would be thrown if the string to search and the replacement string were both zero length strings (i.e., \Code{@""}).

\end{RKLBulletList}

\section{3.0 - 2009/05/06}
\label{ReleaseInformation_30}

This release of \RegexKitLite{} is a major release that includes new features, new APIs, and a number of bug fixes.

New Features:

\begin{RKLBulletList}

  \item DTrace support. This release includes \RegexKitLite{} specific DTrace provider probe points that allow you to monitor the effectiveness of \RegexKitLite{'s}{} caches.  DTrace support can be enabled with the compile time configuration option \CPPFlag{RKL\_DTRACE}.

  \item Easy support for custom built ICU libraries. A new compile time configuration option, \linebreak \CPPFlag{RKL\_APPEND\_TO\_ICU\_FUNCTIONS}, can be used to append a string to the ICU functions called by \linebreak \RegexKitLite{.}  Custom builds of the ICU library include the ICU version appended to all functions by default and this feature allows you to easily retarget \RegexKitLite{} to your custom build. Example \linebreak usage: \ConsoleText{-DRKL\_APPEND\_TO\_ICU\_FUNCTIONS=\_4\_0}

\end{RKLBulletList}

New \Code{NSString} Methods:

\begin{RKLBulletList}

  \item \Code{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\RKLRef{NSString_RegexKitLiteAdditions__-arrayOfCaptureComponentsMatchedByRegex:}{\Bd{arrayOfCaptureComponentsMatchedByRegex:}}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

  \item \Code{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *)\RKLRef{NSString_RegexKitLiteAdditions__-captureComponentsMatchedByRegex:}{\Bd{captureComponentsMatchedByRegex:}}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

  \item \Code{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger}) \RKLRef{NSString_RegexKitLiteAdditions__-captureCount}{\Bd{captureCount}};}

  \item \Code{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSArray\_Class/NSArray.html}{NSArray} *) \RKLRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:}{\Bd{componentsMatchedByRegex:}}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};}

  \item \Code{- (void)\RKLRef{NSString_RegexKitLiteAdditions__-flushCachedRegexData}{\Bd{flushCachedRegexData}};}

  \item \Code{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/ObjCRuntimeRef/Reference/reference.html\#//apple\_ref/c/tdef/BOOL}{BOOL})\RKLRef{NSString_RegexKitLiteAdditions__-isRegexValid}{\Bd{isRegexValid}};}

\end{RKLBulletList}

Deprecated Functionality:

\begin{RKLBulletList}

  \item \Code{+ (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_DataTypes/Reference/reference.html\#//apple\_ref/c/tdef/NSInteger}{NSInteger})\RKLRef{NSString_RegexKitLiteAdditions__.captureCountForRegex:}{\Bd{captureCountForRegex:}}(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};} \Deprecated{Deprecated in \RegexKitLite{ 3.0}}\\

Use of \Code{captureCountForRegex:} is deprecated in favor of \RKLCodePageRef{NSString_RegexKitLiteAdditions__-captureCount}{captureCount}.

  \item \Code{- (\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSEnumerator\_Class/Reference/Reference.html}{NSEnumerator} *)\Bd{matchEnumeratorWithRegex}:(\RKLHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/Reference/NSString.html}{NSString} *)\Argument{regex};} and\newline \Code{RKLMatchEnumerator} \Deprecated{Deprecated in \RegexKitLite{ 3.0}}\\

The example code for \Code{RKLMatchEnumerator} available in \File{examples/RKLMatchEnumerator.h} and \linebreak \File{examples/RKLMatchEnumerator.m} has been deprecated in favor of \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsMatchedByRegex:}{componentsMatchedByRegex:}.

\end{RKLBulletList}

\Bd{Changes that effect the results that are returned:}

\begin{RKLBulletList}
  \item {When the regular expression matched the tail end of the string to search, \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{componentsSeparated\DBrk{}By\DBrk{}Regex:} would incorrectly add a zero length string to the results returned.}

\begin{lstlisting}
NSArray *splitArray = [@"Bob, Tom, Sam," componentsSeparatedByRegex:@",\\s*"];

// { @"Bob", @"Tom", @"Sam", @"" } <- RegexKitLite ≤ v2.2.
// { @"Bob", @"Tom", @"Sam"      } <- RegexKitLite ≥ v3.0.
\end{lstlisting}

  \item The results returned by \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{componentsSeparatedByRegex:} were found to differ from the expected results when zero-width assertions, such as \Regex{\textbackslash{}b}, were used.  Prior to v3.0, regular expressions that matched zero characters would be considered a 'match', and a zero length string would be added to the results array.  The expected results are the results that are returned by the \QuotedText{perl} \Code{split()} function, which does not create a zero length string in such cases.  ICU ticket \#\RKLHref{http://bugs.icu-project.org/trac/ticket/6826}{6826}.

\begin{Verbatim}[commandchars=\\\{\}]
splitArray = [@"I|at|ice I eat rice" componentsSeparatedByRegex:@"\textbackslash{}\textbackslash{}b\textbackslash{}\textbackslash{}s*"];

// [1]: \{\hairspace{}@"",\hairspace{}@"I",\hairspace{}@"|",\hairspace{}@"at",\hairspace{}@"|",\hairspace{}@"ice",\hairspace{}@"",\hairspace{}@"I",\hairspace{}@"",\hairspace{}@"eat",\hairspace{}@"",\hairspace{}@"rice"\hairspace{}\}
// [2]: \{\hairspace{}\nobreakspace{}\nobreakspace{}\nobreakspace{}\nobreakspace{}\hairspace{}@"I",\hairspace{}@"|",\hairspace{}@"at",\hairspace{}@"|",\hairspace{}@"ice",\hairspace{}\nobreakspace{}\nobreakspace{}\nobreakspace{}\nobreakspace{}\hairspace{}@"I",\hairspace{}\nobreakspace{}\nobreakspace{}\nobreakspace{}\nobreakspace{}\hairspace{}@"eat",\hairspace{}\nobreakspace{}\nobreakspace{}\nobreakspace{}\nobreakspace{}\hairspace{}@"rice"\hairspace{}\}

// [1]: ICU  & RegexKitLite ≤ v2.2
// [2]: perl & RegexKitLite ≥ v3.0
\end{Verbatim}

  \item As part of the \HardNobr{64-bit} tidy, a check of the length of a string that is passed to \RegexKitLite{,} and therefore ICU, was added to ensure that the length is less than \Code{INT\_MAX}. If the length of the string is \textgreatereq{} \Code{INT\_MAX}, then \RegexKitLite{} will raise \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Miscellaneous/Foundation\_Constants/Reference/reference.html\#//apple\_ref/doc/c\_ref/NSRangeException}{NSRangeException}.  The value of \Code{INT\_MAX} is $2^{31}-1$ (\Code{0x7fffffff}).  This was done because ICU uses the \Code{int} type for representing offset values.

\end{RKLBulletList}

Other Changes:

\begin{RKLBulletList}
  \item Ticket \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2027975&group\_id=204582&atid=990188}{2027975} - Request for \Code{captureCount} like functionality.
  \item Ticket \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2779301&group\_id=204582&atid=990191}{2779301} - Request for \Code{componentsMatchedByRegex:} functionality.
  \item Ticket \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2779965&group\_id=204582&atid=990188}{2779965} - Request that documentation be updated with how to match a literal \ConsoleText{\textbackslash{}} with a regex specified using a string literal: \ConsoleText{@"\textbackslash{}\textbackslash{}\textbackslash{}\textbackslash{}";}.
  \item Ticket \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2786878&group\_id=204582&atid=990191}{2786878} - Request for \Code{isRegexValid} functionality.
  \item The GCC variable \Code{cleanup} \Code{\_\_attribute\_\_()} is now used to provide an extra safety net around the use of the \RegexKitLite{} spin lock.  The \Code{cleanup} function ensures that if the spin lock was locked by a function that it was also unlocked by the function.  If a function obtains the lock but does not unlock it, the \Code{cleanup} function forcibly unlocks the spin lock.
  \item Minor GC changes.  Some minor changes in the way heap buffers were allocated was required to support the new methods that return a \Code{NSArray}.
  \item \HardNobr{64-bit} cleanup.  Various literal numeric constant values had either \Code{L} or \Code{UL} appended to them if they were used with \Code{NSInteger}, \Code{NSUInteger}, or various other '\Code{long}' data types.
  \item \HardNobr{64-bit} cleanup.  Added checks to verify that a strings length is < \Code{INT\_MAX} and throw an exception if it isn't. This check was added because ICU uses signed \HardNobr{32-bit} \Code{int} values to represent offsets.
  \item Changed some macros to static inline functions for compile-time prototype checking.
  \item Updated \File{examples/NSString-HexConversion.m}.  \HardNobr{64-bit} tidies.
  \item Updated \File{examples/RKLMatchEnumerator.h}.  Added the deprecated attribute to \Code{matchEnu\DLBrk{}mer\DLBrk{}a\DLBrk{}tor\DLBrk{}With\DLBrk{}Regex:}.
  \item Updated \File{examples/RKLMatchEnumerator.m}.  \HardNobr{64-bit} tidies.  Added a preprocessor warning that \linebreak \Code{RKLMatchEnumerator} has been deprecated in favor of \Code{componentsSeparatedByRegex:}.
  \item Updated the documentations visual style to better match the style currently used by Apple.
  \item Many small DocSet tweaks and improvements.
\end{RKLBulletList}

Bug fixes:

\begin{RKLBulletList}

  \item Bug \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2319200&group\_id=204582&atid=990188}{2319200} - The documentation for \Code{stringByReplacingOccurrencesOfRegex:withString:} (and related methods) was updated.  The text for the Returned Value section was obviously copy and pasted from somewhere else and never updated.  This has been fixed.

  \item Bug \#\RKLHref{http://sourceforge.net/tracker/index.php?func=detail&aid=2408447&group\_id=204582&atid=990188}{2408447} - \Code{stringByReplacingOccurrencesOfRegex:} bug fixed. There was a bug in ICU that would cause a search and replace operation to fail with \Code{U\_BUFFER\_OVERFLOW\_ERROR}, which would then cause \RegexKitLite{} to throw \RKLCodePageRef{RKLICURegexException}{RKLICURegexException}, if the length of the replaced string was significantly longer than the original string.  ICU ticket \#\RKLHref{http://bugs.icu-project.org/trac/ticket/6656}{6656}.

  \item \Code{componentsSeparatedByRegex:} bug fixed. When the regular expression matched the tail end of the string, an extra zero length string was incorrectly added to the results.

  \item \Code{componentsSeparatedByRegex:} bug fixed. The results returned by the ICU function \linebreak \Code{uregex\_split()} was found to be different that the results returned by the \ConsoleText{perl} \Code{split()} function.  ICU ticket \#\RKLHref{http://bugs.icu-project.org/trac/ticket/6826}{6826}

  \item \Code{rangeOfRegex}, \Code{stringByMatching:} bug fixed. A bug was fixed where the \Code{inRange:} parameter was not correctly honored.

  \item If \RegexKitLite{} was able to get direct access to a strings \UTF{16} buffer, there was a very remote chance that \RegexKitLite{} would continue to use a pointer to a strings older \UTF{16} buffer if the string mutated and allocated a new buffer.  The pointer to a strings direct buffer is now verified before each use.

  \item \Code{isMatchedByRegex:inRange:} was never documented.  Fixed.

\end{RKLBulletList}

\section{3.1 - 2009/05/15}
\label{ReleaseInformation_31}

This release of \RegexKitLite{} is a bug fix release.

Bug Fixes:

\begin{RKLBulletList}
  \item Bug \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2790480&group\_id=204582&atid=990188}{2790480} - If a regular expression had an error, as detected by ICU, then under some circumstances the \Code{lastCacheSlot} variable would not be properly cleared.  As a result, this would cause the pointer to the compiled regular expression to be \Code{NULL}.  The \Code{NULL} value would be caught by the run-time assertion checks if they were not disabled via \CPPFlag{NS\_BLOCK\_ASSERTIONS}, otherwise it would most likely lead to a crash.
\end{RKLBulletList}

\section{3.2 - 2009/11/04}
\label{ReleaseInformation_32}

This release of \RegexKitLite{} is a bug fix release.

Bug Fixes:

\begin{RKLBulletList}

  \item Bug \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2828966&group\_id=204582&atid=990188}{2828966}  - Fixed a minor bug that caused compiling on \MacOSX{ 10.4} to fail.  Changed the header include line from \Code{\#include~<objc/runtime.h>}, which is available only on \MacOSX{ \textgreatereq{} 10.5}, to\DLBRK{} \Code{\#include~<objc/objc-runtime.h>}, which is available on \MacOSX{ \textgreatereq{} 10.4}.

  \item Bug \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2862398&group\_id=204582&atid=990188}{2862398}  - Modified the logic for determining if the cached \UTF{16} conversion is valid for the string to be searched.  Previously, \RegexKitLite{} used a combination of the string to be searched \Code{hash} and \Code{length} to determine if the cached \UTF{16} conversion was a match.  For speed, \Code{NSString} only uses a fixed number of characters to calculate the hash.  This means that as the length of a string grows, the hash function becomes less effective at detecting differences between strings.  The original intent behind the \UTF{16} conversion cache logic was to be able to re-use the \UTF{16} conversion for strings that were "the same" (i.e., hash equality), but were different instantiations (i.e., pointer inequality).  On reflection, it was decided that the more likely real-world case would be strings that would share the same hash value, but actually be slightly different.  \RegexKitLite{} now requires that the \Code{NSString} pointer, as well as the \Code{hash} and \Code{length}, be the same as the string used for the cached \UTF{16} conversion.

  \item  Bug \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2879356&group\_id=204582&atid=990188}{2879356} - \Code{arrayOfCaptureComponentsMatchedByRegex:}, \Code{cap\DLBrk{}ture\DLBrk{}Com\DLBrk{}po\DLBrk{}nents\DLBrk{}Matched\DLBrk{}ByRegex:}, \Code{componentsMatchedByRegex:}, and \Code{componentsSeparatedByRegex:} bug fixed.  Originally reported by Jesse Grosjean. Duplicate of bug \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2890342&group\_id=204582&atid=990188}{2890342}.  If a regex matched a part of the string that included the very end of the string, subsequent matches would incorrectly return that the regex did not match the string.  Clearing the cache, either manually or because another regex match replaced the affected cache slot, would clear the condition.

  \item Bug \#\RKLHref{http://sourceforge.net/tracker/?func=detail&atid=990188&aid=2890810&group\_id=204582}{2890810}  - \Code{stringByReplacingOccurrencesOfRegex:} bug fixed.  If the size of the buffer needed to hold the replaced string was larger than the initial estimated buffer size, ICU should return an error of \Code{U\_BUFFER\_OVERFLOW\_ERROR}.  However, due to a bug in ICU (see bug \#\RKLHref{http://sourceforge.net/tracker/index.php?func=detail&aid=2408447&group\_id=204582&atid=990188}{2408447}, ICU ticket \#\RKLHref{http://bugs.icu-project.org/trac/ticket/6656}{6656}), this error was not reported correctly and a workaround was implemented.  A rare corner case could cause ICU to return \Code{U\_STRING\_NOT\_TERMINATED\_WARNING} during the time that \RegexKitLite{} was calculating the size of the buffer needed to hold all of the replaced string.  When this happened it would cause \RegexKitLite{} to miss the \Code{U\_BUFFER\_OVERFLOW\_ERROR} error needed to resize the buffer.

\end{RKLBulletList}

\section{3.3 - 2009/11/07}
\label{ReleaseInformation_33}

This release of \RegexKitLite{} is a bug fix release.

Bug Fixes:

\begin{RKLBulletList}
  \item Bug \#\RKLHref{http://sourceforge.net/tracker/?func=detail&atid=990188&aid=2893824&group\_id=204582}{2893824} - Fixed a minor bug that caused compiling with the iPhone device SDK to fail.  This is related to the \RegexKitLite{ 3.2} fix for bug \#\RKLHref{http://sourceforge.net/tracker/?func=detail&aid=2828966&group\_id=204582&atid=990188}{2828966}.  It turns out that the iPhone simulator SDK \linebreak has the header file \File{objc/objc-runtime.h}, but the iPhone device SDK only has the header file \linebreak \File{objc/runtime.h}.  \RegexKitLite{} will now conditionally use \Code{\#include~<objc/runtime.h>} when \linebreak targeting the iPhone or \MacOSX{ \textgreatereq{} 10.5}, and \Code{\#include~<objc/objc-runtime.h>} when targeting \linebreak \MacOSX{ \textlesseq{} 10.4}.
\end{RKLBulletList}

\section{4.0 - 2010/04/18}\label{ReleaseInformation_40}\label{ReleaseInformation_ThisVersion}
This release of \RegexKitLite{} is a major release that includes new features, new APIs, and bug fixes.

\Bd{API Compatibility Changes:}

\begin{RKLBulletList}
  \item The \Code{NSMutableString} \Code{replaceOccurrencesOfRegex:}\textellipsis{} methods now return a result of type \linebreak \Code{NSInteger}, whereas \RegexKitLite{ < 4.0} returned a result of type \Code{NSUInteger}. This change, while technically breaking API compatibility, is likely to be completely backwards compatible for most users. The change was made so that errors, such as an invalid regular expression, can be distinguished from a search and replace operation that replaced zero occurrences. An error condition that is not an exception now returns a value of \Code{-1}. Prior to \RegexKitLite{ 4.0,} the only way to distinguish between a search and replace operation that replaced zero occurrences and an error that prevented a search and replace from taking place was to use a \Code{replaceOccurrencesOfRegex:}\textellipsis{} method with an \Code{error:} parameter.
\end{RKLBulletList}

\Bd{Changes that effect the results that are returned:}

\begin{RKLBulletList}

  \item The results returned by \RKLCodePageRef{NSString_RegexKitLiteAdditions__-componentsSeparatedByRegex:}{componentsSeparatedByRegex:} were found to differ from the expected results for some regex patterns. For example, prior to v4.0, when the regular expression \Regex{.} (dot, match any character) was used to split a string, \RegexKitLite{} returned an array of seven zero length strings.  The expected results are the results that are returned by the \QuotedText{perl}\Code{~}\Code{split()} function\textendash{} the equivalent of a \Code{NSArray} with zero items in it.

\begin{lstlisting}
NSArray *splitArray = [@"abc.def" componentsSeparatedByRegex:@"."];

// { @"", @"", @"", @"", @"", @"", @"" } <- RegexKitLite ≤ v3.3.
// {                                   } <- RegexKitLite ≥ v4.0 & perl.
\end{lstlisting}

\end{RKLBulletList}

New features:

\begin{RKLBulletList}
  \item Documentation now available in PDF format.\\

The \RegexKitLite{} documentation is now available in PDF format.  The PDF version is ideal for making printed copies of the documentation.

  \item Improved compiled regular expression cache.\\

\RegexKitLite{} \HardNobr{versions < 4.0} used a direct mapped, or \HardNobr{1-way} set associative, cache.  \RegexKitLite{ 4.0} uses a \HardNobr{4-way} set associative cache.  In general, a \HardNobr{\textit{n}-way} set associative cache, where \HardNobr{\textit{n} > \Code{1},} has fewer misses than a direct mapped cache.  Entries in a set are managed on a least recently used, or LRU, basis.  This means that when a compiled regular expression is added to the cache, the entry in a set that is the least recently used is the one chosen to hold the new compiled regular expression.\\

In benchmark tests, the old compiled regular expression cache required a \BdIt{dramatically} larger cache size to achieve the same effectiveness (i.e., the likelihood that the regular expression was already in the cache) as the new compiled regular expression cache. Retrieving a cached compiled regular expression is \BdIt{541.3} times faster$^{\dag}$ than actually compiling the regular expression:\\

\begin{tabular}{|l|r|r|}\hline
\rowcolor[gray]{0.8862745}
\Bd{Retrieve} & \Bd{Time} & \Bd{Rate (per second)} \\\hline
\Bd{Cached}   &     51 ns & 19,680,762 \\\hline
\Bd{Compile}  & 27,560 ns &     36,285 \\\hline
\end{tabular}\\
\vspace{4pt}

$^{\dag}$~Timing done a MacBook Pro 2.66GHz running \MacOSX{ 10.6.2}.

  \item Improved \UTF{16} conversion cache.\\

The \UTF{16} conversion cache now uses the same \HardNobr{4-way} set associative cache system as the compiled regular expression cache.  For strings that required a \UTF{16} conversion, \RegexKitLite{} \HardNobr{versions < 4.0} used two buffers for caching \UTF{16} conversions\textendash{} a small, fixed sized buffer for 'small' \HardNobr{strings (\textlesseq{} \Code{2048}} characters by default), and a dynamically sized buffer for 'large' strings.  \RegexKitLite{ 4.0} keeps the same fixed and dynamic size dichotomy, but now each type contains four buffers which are reused on a least recently used basis.

  \item Blocks support.\\

Although support for blocks was introduced with \MacOSX{ 10.6}, you can still use blocks on \linebreak \MacOSX{ 10.5} and \HardNobr{iPhone \textgreatereq{} 2.2} by using \RKLHref{http://code.google.com/p/plblocks/}{Plausible Blocks}.  This solution provides a compiler and runtime that has been back-ported from the \MacOSX{ 10.6} Snow Leopard sources.
\RKLBoxNote{\RegexKitLite{} checks if the C preprocessor define \CPPFlag{NS\_BLOCKS\_AVAILABLE} is set\DLBRk{} \HardNobr{to \Code{1}} to automatically determine if blocks functionality should be enabled.  Typically \CPPFlag{NS\_BLOCKS\_AVAILABLE} is only set to \Code{1} when using the standard developer tools and the minimum version of \MacOSX{}{} supported is set to 10.6.  \RegexKitLite{} blocks support can be explicitly enabled by setting \CPPFlag{RKL\_BLOCKS} to \Code{1} (i.e., \ConsoleText{-DRKL\_BLOCKS=1}).  The behavior is undefined if \CPPFlag{RKL\_BLOCKS} is set to \Code{1} and the compiler does not support the blocks language extension or if the run-time does not support blocks.}

  \begin{RKLSeeAlso}
    \item \RKLSectionHref{http://code.google.com/p/plblocks/}{Plausible Blocks - PLBlocks}
  \end{RKLSeeAlso}\par\vskip\parskip

\end{RKLBulletList}\par\vskip\parskip

New \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/index.html}{NSString} Methods:

\begin{RKLBulletList}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-dictionaryByMatchingRegex:withKeysAndCaptures:}{- dictionaryByMatchingRegex:withKeysAndCaptures:}

  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:}{- arrayOfDictionariesByMatchingRegex:withKeysAndCaptures:}

\end{RKLBulletList}

New Block-based \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString\_Class/index.html}{NSString} Methods:

\begin{RKLBulletList}
  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsMatchedByRegex:usingBlock:}{- enumerateStringsMatchedByRegex:usingBlock:}

  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-enumerateStringsSeparatedByRegex:usingBlock:}{- enumerateStringsSeparatedByRegex:usingBlock:}

  \item \RKLCodePageRef{NSString_RegexKitLiteAdditions__-stringByReplacingOccurrencesOfRegex:usingBlock:}{- stringByReplacingOccurrencesOfRegex:usingBlock:}

\end{RKLBulletList}
	
New Block-based \RKLCodeHref{http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSMutableString\_Class/index.html}{NSMutableString} Methods:

\begin{RKLBulletList}
  \item \RKLCodePageRef{NSMutableString_RegexKitLiteAdditions__-replaceOccurrencesOfRegex:usingBlock:}{- replaceOccurrencesOfRegex:usingBlock:}
\end{RKLBulletList}

Other changes:

\begin{RKLBulletList}

  \item Improved performance.  Many small performance tweaks and optimizations were made to frequently used code paths.

  \item The meaning of \CPPFlag{RKL\_CACHE\_SIZE} changed.  This compile-time preprocessor tunable now controls the number of "sets" in the compiled regular expression cache, and each "set" contains four entries.  This means that the maximum number of potential compiled regular expressions that can be cached is \linebreak \CPPFlag{RKL\_CACHE\_SIZE} times four.  Like previous versions, \CPPFlag{RKL\_CACHE\_SIZE} should always be a prime number to maximize the use of the cache.

  \item \CPPFlag{RKL\_CACHE\_SIZE} changed \HardNobr{to \Code{13}.}  The total number of compiled regular expressions that can be cached \HardNobr{is \Code{13 * 4},} \HardNobr{or \Code{52}.}  This is \HardNobr{a 126\%} increase from previous versions of \RegexKitLite{} which had a default value \HardNobr{of \Code{23}} for \CPPFlag{RKL\_CACHE\_SIZE}.

  \item Added the flag \RKLCodePageRef{RKLEnumerationBufferLookupFlag}{RKLEnumerationBufferLookupFlag} to the DTrace\DLBrk{} \RKLCodePageRef{dtrace_utf16ConversionCache_lookupResultFlags}{RegexKitLite:::utf16\DLBrk{}Con\DLBrk{}ver\DLBrk{}sion\DLBrk{}Cache} flags.

  \item Added a number of new keys to \RKLSectionPageRef{RegexKitLiteNSErrorandNSExceptionUserInfoDictionaryKeys}{\RegexKitLite{} NSError and NSException User Info Dictionary Keys}.

\end{RKLBulletList}

Bug fixes:

\begin{RKLBulletList}

  \item If the ICU library returned a status of \Code{U\_STRING\_NOT\_TERMINATED\_WARNING} during a search and replace operation, \RegexKitLite{} erred on the side of caution and treated it as a failure due to the numerous search and replace bugs in the past.  \RegexKitLite{ 4.0} continues to err on the side of caution, but now treats \Code{U\_STRING\_NOT\_TERMINATED\_WARNING} as if the ICU library had returned a status code of \Code{U\_BUFFER\_OVERFLOW\_ERROR}.

  \item The \Code{NSMutableString} \HardNobr{\Code{replaceOccurrencesOfRegex:}\textellipsis{}} methods could have returned a \HardNobr{value > \Code{0},} the replaced count, even if no actual replacements were performed.  This would occur if an error was encountered during the search and replace, in which case the replaced count was not correctly reset \HardNobr{to \Code{0}.}  \RegexKitLite{ 4.0} changed the \HardNobr{\Code{replaceOccurrencesOfRegex:}\textellipsis{}} API so that a value \HardNobr{of \Code{-1}} could be returned to indicate that an error was encountered.

  \item \Code{componentsSeparatedByRegex:} bug fixed. The results returned were found to be different that the results returned by the \ConsoleText{perl} \Code{split()} function.

\end{RKLBulletList}

\titleformat{\section}{\normalfont\fontsize{19pt}{19pt}\rmfamily}{\thesection.}{.5em}{}
\titlespacing{\section}{-50pt}{*3}{*3}


\labeledchapter{Epilogue}{Epilogue}

\section{Coding Style}

One noticeable break in style conventions is in line lengths. There was a time when 80 column limits made a lot of sense as it was the lowest common denominator. Today, a modern computer screen can display much more than just 80 columns.  Even an iPhone, which has a screen size of 320x480, can display 96 columns by 24 rows of the usual Terminal.app Monaco 10pt font (5x13 pixels) in landscape mode.  Because of this, my personal style is not to have an arbitrary limit on line lengths. This allows for much more code to fit on the screen at once, which I've heard referred to as "Man\textendash{}Machine Interface Bandwidth". While you can always page up and down, the simple movement of your eye is almost always an order of magnitude faster. Paging through code also tends to break your concentration as you briefly try to mentally orientate yourself with the freshly displayed text and where the section of code is that you're looking for.

I try to group a line around relevancy so that based on the start of the line you can quickly determine if the rest of the line is applicable. Clearly the number of spaces used to indent a block plays a similar role, it allows you to quickly visually establish the logical boundaries of what lines of code are applicable. I also try to horizontally align related statements since your eye tends to be extremely sensitive to such visual patterns. For example, in variable declaration and initialization, I try to align the type declaration and the \Code{=} (equal sign) across multiple lines. This tends to cause the declaration type, the variable name, and the value assigned to visually \It{pop}. Without the alignment, you typically have to scan back and forth along a line to separate and find a variable name and its initialization value. Sometimes line breaks and horizontal alignment are done purely on what's subjectively aesthetically pleasing and allows the eye to quickly \It{flow} over the code.

The source code of \RegexKitLite{} isn't exactly what you'd call clean, there's more than a few crufty C barnacles in there.  There is usually a choice between two polar opposites and in this case it's between elegant, easy to maintain and comprehend code, and speed.  If you use regular expressions for very long, you will undoubtedly encounter a situation where you need to scan through tens of megabytes of text and the speed of your regular expression matching loop needs to be faster.  \BdIt{A lot faster}.  \RegexKitLite{} was written to go fast, and the source code style reflects this choice.

\subsubsection{The Need for Speed}

A significant amount of time was spent using Shark to optimize the critical sections of \RegexKitLite{}.  This included tweaking even the most insignificant details, such as the order of boolean expressions in \Code{if()} statements to minimize the number of branches that would have to be evaluated to determine if the statement is true or false. Wherever possible, \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation} is used directly. This avoids the overhead of an \ObjectiveC{} message dispatch, which would invariably end up calling the exact same \RKLSectionHref{http://developer.apple.com/mac/library/documentation/CoreFoundation/Reference/CoreFoundation\_Collection/index.html}{Core Foundation} function anyways.

Even the cache has what is essentially a cache\textendash{} the last regular expression used.  Each time a regular expression is used, the compiled ICU regular expression must be retrieved from the cache, or if it does not exist in the cache, instantiated.  Checking the cache involves calculating the remainder of the regular expression strings hash modulo the cache size prime, which is a moderately expensive division and multiplication operation.  However, checking if the regular expression being retrieved this time is exactly the same as the last regular expression retrieved is just a fast and simple comparison check.  As it turns out, this is very often the case.  Even the functions are arranged in such a way that the compiler will often inline everything in to one large aggregate function, eliminating the overhead of a function call in many places.

Normally, this kind of micro-optimization is completely unjustified. A rough rule of thumb is that 80\% of your programs execution time is spent in 20\% of your programs code.  The only code worth optimizing is the 20\% that is heavily executed. If your program makes heavy use of regular expressions, such as a loop that scans megabytes of text using regular expressions, \RegexKitLite{} is almost guaranteed to be a part of the 20\% of code where most of the execution time is spent.  The release notes for \RKLHref{http://osx.iusethis.com/app/versions/coteditor}{CotEditor} would seem to indicate that all this effort has paid off for at least one user:

\RKLBoxQuote{\QuotedText{More than 10.4 when running on the color process to review the details of the definition of a regular expression search RegexKitLite adopted, 0.9.3, as compared to the speed of color from 1.5 to 4 times as much improved.}

\RKLBoxNote{This is an automatic machine translation from Japanese to English.}}

\section{Documentation}

Clearly documentation has been a high priority for this project.  Documentation is always hard to write and good documentation is exponentially harder still.  The vast majority of 'development effort and time' is spent on the documentation.  It's always hard to judge the quality and effectiveness of something you wrote, so hopefully the extra effort is worth it and appreciated.

As an aside and a small rant, I have no idea how anyone manages to build so-called 'web applications'.  I waste a truly unbelievable amount of time trying to accomplish the simplest of things in HTML, which is then multiplied when I check for 'compatibility' with different browsers and their various popular versions.  What a joke, and that's just for this 'simple' documentation.  Though I do have to give kudos to the Safari / WebKit guys, it always seems to be a lot easier to get the result you're looking for with the WebKit engine.  The little things add so much: shadows, round rects, gradients, CSS animations, the canvas element, etc.

\section{Questions about licensing, including in your software, etc}

\begin{minipage}[t]{\linewidth}
\Bd{What do I need to do to include \RegexKitLite{} in my software?}\par
\RKLOffset{4ex}{Not much.  The \textit{BSD License} is very permissive.  In short, you just need to 'acknowledge' your use of it.  Safari's \MenuText{Help \MenuRightArrow{} Acknowledgements} is a good example of this.}
\end{minipage}

\begin{minipage}[t]{\linewidth}
\Bd{I am selling a 'closed-source' commercial application.  I would like to use \RegexKitLite{} in it, how much will it cost?}\par
\RKLOffset{4ex}{\RegexKitLite{} is free for any use.}
\end{minipage}

\begin{minipage}[t]{\linewidth}
\Bd{Do I have to distribute the source with my application?}\par
\RKLOffset{4ex}{No.  Unlike the \RKLSectionHref{http://www.gnu.org/licenses/licenses.html}{GNU GPL License}, there is no requirement that you include or make the source code available, even if you release a "compiled, binaries only" end product.}
\end{minipage}

\begin{minipage}[t]{\linewidth}
\Bd{What about modifications to \RegexKitLite{?}  Do I have to make any changes that I make available?  Or contribute them back to the author of \RegexKitLite{?}}\par
\RKLOffset{4ex}{You may make any modifications you want and are under no obligation to release those changes to anyone.}
\end{minipage}

\begin{minipage}[t]{\linewidth}
\Bd{Why the \textit{BSD License}?}\par
\RKLOffset{4ex}{It's a well known license.  If you are part of a Large Corporate Organization, chances are the Corporate Lawyers have Decided whether or not the use of source code licensed under the \textit{BSD License} is Acceptable or not.  This can be a godsend for anyone who has to deal with such situations.\\

It also expresses a few things I think are perfectly reasonable:

\begin{enumerate}
  \item Give credit where credit is due.
  \item There is no warranty, so use it at your own risk.
  \item You can't hold the author responsible.
\end{enumerate}

The first point is prescribed by most professional ethics already.  Plus, it's always nice to see where your stuff ends up and how it's being used.  The other points make explicit what should already be obvious.  After all, you get what you pay for.}
\end{minipage}

\RKLAppendix

\labeledchapter{LicenseInformation}{License Information}
  
\RegexKitLite{} is distributed under the terms of the \textit{BSD License} as specified below.
  
\begin{RKLSeeAlso}
  \item \RKLSectionHref{http://en.wikipedia.org/wiki/BSD\_license}{Wikipedia - BSD License}
  \item \RKLSectionHref{http://www.linfo.org/bsdlicense.html}{The Linux Information Project - BSD License Definition}
\end{RKLSeeAlso}

\section{License}

Copyright \textcopyright{} 2008-2010, John Engelhart

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

\begin{enumerate}[label=\textbullet{}]
  \item Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  \item Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  \item Neither the name of the Zang Industries nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
\end{enumerate}

{\fontspec[Scale=MatchLowercase]{Courier}THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.}

%\showhyphens{}

\end{document}
